# openbci/openbci_gui architecture

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

- Interactive diagram: https://gitdiagram.com/openbci/openbci_gui
- Repository: https://github.com/openbci/openbci_gui

## Overview

##### Main Components
a. User Interface (UI) Layer – This is implemented using Processing. The “OpenBCI_GUI” directory contains most of the .pde files that control widgets, panels, and overall visual rendering. Libraries such as controlP5 (for UI elements) and oscP5 (for networking) are used here.
b. Hardware Abstraction and Device Interface – The application supports multiple devices (Cyton, Ganglion, Cyton with Daisy) and includes board-specific classes (e.g., BoardCyton, BoardGanglion). These modules abstract direct communication with hardware.
c. Data Acquisition and Processing – Data gets filtered and processed in real time. This includes filtering modules, data logging (DataLogger, DataProcessing, DataWriter modules) and a buffering system. The project also provides the ability for offline playback.
d. Networking and External Communication – There are dedicated subdirectories such as “Networking-Test-Kit” that include support for UDP, OSC, LSL, Serial communication, etc. These components allow streaming data from the GUI to external applications (for example, MATLAB) or other systems.
e. Unit Testing and Tools – The “GuiUnitTests” and “tools” directories indicate that the system is well-structured for testing. The tests exercise various parts of the GUI and data acquisition logic.
f. External Libraries and Frameworks – The file tree shows a large number of libraries (e.g., brainflow, LSLLink, controlP5, oscP5, minim) which are used to extend functionality. They need to be represented as separate modules or as an “Integration Layer.”

##### Relationships and Data Flow
- Data originates at the hardware level where signals are acquired from OpenBCI devices.
- The Hardware Abstraction Layer converts raw signals into a format the application can process.
- This data flows into the data processing components for filtering, buffering, and logging.
- The processed data then feeds the UI, which displays the real-time signals (and provides widget interactivity).
- In parallel, a networking layer sends or streams the data out over protocols such as UDP, OSC, Serial or LSL.
- Unit tests and build scripts interact with many layers to ensure integration and facilitate continuous deployment (as seen in the “.github/workflows” and “release” directories).

##### Architectural Patterns and Design Principles
- Separation of Concerns – Different layers (UI, hardware integration, data processing, and networking) are clearly separated.
- Modular Design – Each directory and library encapsulates a specific domain (for example, control elements are in controlP5, audio processing in minim, and so on).
- Platform Portability – With dedicated build and deployment scripts for macOS, Windows, and Linux, the architecture is designed to abstract platform-specific code.
- Extensibility – The support for custom widgets and experimental modules (see “widgets” and custom GUI components) indicates an extensible plugin-like framework.

##### Additional Elements
- Major external dependencies (e.g., OpenBCI devices, BrainFlow libraries, LSLLink, oscP5, controlP5, etc.) to show how they integrate into the system.
- How configuration and build scripts (found in the “tools” and “release” directories) fit into the overall deployment pipeline.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI["OpenBCI_GUI (UI Layer)"]
    end

    %% Hardware Abstraction & Data Acquisition Layer
    subgraph "Hardware & Data Acquisition Layer"
        %% Hardware Abstraction
        subgraph "Hardware Abstraction"
            BC["BoardCyton"]
            BG["BoardGanglion"]
        end
        %% Data Acquisition and Processing
        subgraph "Data Acquisition & Processing"
            DL["Data Logger"]
            DP["Data Processing"]
            BF["Buffer"]
        end
    end

    %% Networking Layer
    subgraph "Networking Layer"
        UDP["UDP"]
        OSC["OSC"]
        LSL["LSL"]
    end

    %% Support & Tools
    subgraph "Support & Tools"
        UT1["GuiUnitTests"]
        UT2["Tools"]
        BD1[".github/workflows"]
        BD2["release"]
    end

    %% External Libraries & Frameworks
    subgraph "External Libraries"
        LIB["Libraries"]
        GAH["GUI Helpers"]
    end

    %% Data flow connections
    BC -->|"sends data"| DL
    BG --> DL
    DL --> DP
    DP --> BF
    BF -->|"updates UI"| UI
    BF -->|"streams data"| UDP
    BF --> OSC
    BF --> LSL

    %% External Libraries support
    LIB -->|"supports"| UI
    LIB -->|"supports"| BC
    LIB --> DP
    GAH --> UI

    %% Support & Tools interactions
    UT1 -->|"tests"| UI
    UT1 --> DP
    BD1 -->|"builds"| UI
    BD2 --> UI

    %% Class definitions for styling
    classDef ui fill:#BBDEFB,stroke:#1E88E5,stroke-width:2px;
    classDef hardware fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef processing fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
    classDef network fill:#F8BBD0,stroke:#C2185B,stroke-width:2px;
    classDef testing fill:#E0E0E0,stroke:#757575,stroke-width:2px;
    classDef build fill:#D1C4E9,stroke:#7E57C2,stroke-width:2px;
    classDef externals fill:#B2EBF2,stroke:#0097A7,stroke-width:2px;

    class UI ui;
    class BC,BG hardware;
    class DL,DP,BF processing;
    class UDP,OSC,LSL network;
    class UT1,UT2 testing;
    class BD1,BD2 build;
    class LIB,GAH externals;

    %% Click Events for UI Layer
    click UI "https://github.com/openbci/openbci_gui/blob/master/OpenBCI_GUI/OpenBCI_GUI.pde"

    %% Click Events for Hardware Abstraction
    click BC "https://github.com/openbci/openbci_gui/blob/master/OpenBCI_GUI/BoardCyton.pde"
    click BG "https://github.com/openbci/openbci_gui/blob/master/OpenBCI_GUI/BoardGanglion.pde"

    %% Click Events for Data Acquisition and Processing
    click DL "https://github.com/openbci/openbci_gui/blob/master/OpenBCI_GUI/DataLogger.pde"
    click DP "https://github.com/openbci/openbci_gui/blob/master/OpenBCI_GUI/DataProcessing.pde"
    click BF "https://github.com/openbci/openbci_gui/blob/master/OpenBCI_GUI/Buffer.pde"

    %% Click Events for Networking Layer
    click UDP "https://github.com/openbci/openbci_gui/tree/master/Networking-Test-Kit/UDP"
    click OSC "https://github.com/openbci/openbci_gui/tree/master/Networking-Test-Kit/OSC"
    click LSL "https://github.com/openbci/openbci_gui/tree/master/Networking-Test-Kit/LSL"

    %% Click Events for Support & Tools
    click UT1 "https://github.com/openbci/openbci_gui/tree/master/GuiUnitTests"
    click UT2 "https://github.com/openbci/openbci_gui/tree/master/tools"
    click BD1 "https://github.com/openbci/openbci_gui/tree/master/.github/workflows"
    click BD2 "https://github.com/openbci/openbci_gui/tree/master/release"

    %% Click Events for External Libraries
    click LIB "https://github.com/openbci/openbci_gui/tree/master/OpenBCI_GUI/libraries"
    click GAH "https://github.com/openbci/openbci_gui/tree/master/OpenBCI_GUI/libraries/openbci_gui_helpers"
```
