# braingeneers/braindance architecture

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

- Interactive diagram: https://gitdiagram.com/braingeneers/braindance
- Repository: https://github.com/braingeneers/braindance

## Overview

##### Project type and purpose
- BrainDance is an open‐source Python toolkit for running neural stimulation experiments, doing real‐time spike detection/sorting, and post‐hoc analysis.
- It bundles drivers for two hardware backends (Maxwell stimulation hardware and Open Ephys acquisition) plus machine‐learning–based spikedetection and optional integration with Kilosort2.

##### File structure and core modules
- Top‐level package: `braindance/`
- `analysis/`: post‐hoc data‐loading and analysis utilities
- `core/`: heart of the system
– `base_env.py` + `maxwell_env.py` + `open_ephys_env.py`: hardware abstractions
– `artifact_removal.py`, `phases.py`, `params.py`: signal‐processing primitives
– `spikedetector/`: ML models (PyTorch) for real‐time detection
– `spikesorter/`: wrappers for Kilosort2 and RT‐Sort flows
– `trainer.py`: orchestrates training of detection models
- `experiments/`: user scripts to define and run stimulation protocols
- `gui/`: user interface layer and static resources
- Other files:
- `requirements.txt` / `setup.py` (package config)
- `gen_docs.py` (docs generator)

##### README insights
- Emphasizes conda/PIP installation, optional RT‐Sort (Torch‐TensorRT), and Kilosort2 integration.
- Notes optional dependency on `open-ephys-python-tools`.

##### Main components
A. Hardware & Data Sources
1. Maxwell stimulation hardware (via `maxwell_env`)
2. Open Ephys acquisition (via `open_ephys_env`)
B. Core Library Layers
1. Base Environment API (`base_env`)
2. Signal Processing
– Artifact Removal
– Phase & Parameter Management
3. Spikedetector (ML inference)
4. Spikesorter (external algorithm wrappers)
5. Trainer (model training pipeline)
C. User‐Facing Layers
1. Experiments scripts (CLI or Python API)
2. GUI application
D. Analysis Subsystem
– `analysis/data_loader` for post‐hoc processing
E. External Dependencies
– PyTorch (+ Torch‐TensorRT)
– Kilosort2 repository
– open‐ephys‐python‐tools

##### Relationships and data flows
- Experiments and GUI bootstrap and control the Core Library; they feed parameters and receive real‐time data/plots.
- Analysis module reads data files produced by Core Library for offline analysis.
- External libraries plugged into specific layers (e.g. PyTorch under Spikedetector, Kilosort2 under Spikesorter).

##### Architectural patterns and principles
- Layered architecture: hardware‐abstraction → processing → user orchestration.
- Modular plugin style for environment backends and sorting algorithms.
- Clear separation of real‐time (spikedetector) vs. offline (analysis) concerns.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware Interfaces"
        direction TB
        Maxwell["Maxwell Stimulation Hardware Interface"]:::hardware
        MaxwellUtils["Maxwell Hardware Utilities"]:::hardware
        OpenEphys["Open Ephys Acquisition Interface"]:::hardware
    end

    %% Core Library Layer
    subgraph "Core Library"
        direction TB
        BaseEnv["Base Environment API"]:::core
        ArtifactRemoval["Artifact Removal"]:::core
        PhaseMgmt["Phase Management"]:::core
        ParamMgmt["Parameter Management"]:::core
        Spikedetector["Spikedetector (ML Inference)"]:::core
        Spikesorter["Spikesorter (Algorithm Wrappers)"]:::core
        Trainer["Trainer (Model Training)"]:::core
    end

    %% User Interfaces Layer
    subgraph "User Interfaces"
        direction TB
        Experiments["Experiments Scripts"]:::user
        GUI["GUI Application"]:::user
    end

    %% Analysis Subsystem
    subgraph "Analysis Subsystem"
        direction TB
        DataLoader["Data Loader (Post-hoc)"]:::core
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        PyTorch["PyTorch / Torch-TensorRT"]:::external
        Kilosort2["Kilosort2 Repository"]:::external
        OEPython["open-ephys-python-tools"]:::external
    end

    %% Data Flows
    Maxwell -->|raw signal| BaseEnv
    OpenEphys -->|raw signal| BaseEnv
    BaseEnv -->|pre-process| ArtifactRemoval
    ArtifactRemoval -->|clean signal| Spikedetector
    Spikedetector -->|spike candidates| Spikesorter
    Spikesorter -->|sorted spikes| Trainer
    Trainer -->|model artifacts| Experiments
    Spikedetector -->|real-time data| Experiments
    Experiments -->|control commands| BaseEnv
    GUI -->|control commands| BaseEnv
    Trainer -->|data files| DataLoader
    DataLoader -->|analysis outputs| Experiments

    %% External integrations
    Spikedetector -->|uses ML libs| PyTorch
    Spikesorter -->|wraps algorithms| Kilosort2
    BaseEnv -->|optional tools| OEPython

    %% Click Events
    click Maxwell "https://github.com/braingeneers/braindance/blob/main/braindance/core/maxwell_env.py"
    click MaxwellUtils "https://github.com/braingeneers/braindance/tree/main/braindance/core/maxwell/"
    click OpenEphys "https://github.com/braingeneers/braindance/blob/main/braindance/core/open_ephys_env.py"
    click BaseEnv "https://github.com/braingeneers/braindance/blob/main/braindance/core/base_env.py"
    click ArtifactRemoval "https://github.com/braingeneers/braindance/blob/main/braindance/core/artifact_removal.py"
    click PhaseMgmt "https://github.com/braingeneers/braindance/blob/main/braindance/core/phases.py"
    click ParamMgmt "https://github.com/braingeneers/braindance/blob/main/braindance/core/params.py"
    click Spikedetector "https://github.com/braingeneers/braindance/tree/main/braindance/core/spikedetector/"
    click Spikesorter "https://github.com/braingeneers/braindance/tree/main/braindance/core/spikesorter/"
    click Trainer "https://github.com/braingeneers/braindance/blob/main/braindance/core/trainer.py"
    click Experiments "https://github.com/braingeneers/braindance/tree/main/braindance/experiments/"
    click GUI "https://github.com/braingeneers/braindance/tree/main/braindance/gui/"
    click DataLoader "https://github.com/braingeneers/braindance/blob/main/braindance/analysis/data_loader.py"

    %% Styles
    classDef hardware fill:#ADD8E6,stroke:#000;
    classDef core fill:#90EE90,stroke:#000;
    classDef user fill:#FFA500,stroke:#000;
    classDef external fill:#D3D3D3,stroke:#000;
```
