# symphony-das/symphony-core architecture

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

- Interactive diagram: https://gitdiagram.com/symphony-das/symphony-core
- Repository: https://github.com/symphony-das/symphony-core

## Overview

##### Project Type and Purpose
- This is an open‐source, modular data‐acquisition framework (“Symphony Core”) written in C#/.NET with C++ interop layers.
- Its goal is to provide a unified API for recording, streaming, and persisting electrophysiology data from multiple hardware sources (Heka ITCMM, NI DAQ, simulated DAQ) and external devices (Axopatch, MultiClamp).

##### High‐level Architectural Layers
- Layer 1: Client Applications & Tools
- MessageTrapper (diagnostics)
- HekaSandbox (demo/test harness)
- Installer (WiX Setup project)
- Layer 2: Core Framework (Symphony.Core)
- Defines abstractions: IHardwareController, DAQStream, Epoch, Measurement, Pipeline, IEpochPersistor
- Orchestrates device controllers, data streams, event scheduling
- Layer 3: Hardware Controller Plugins
- HekaDAQController
- NIDAQController
- SimulationDAQController
- Each implements IHardwareController and provides Input/Output streams
- Layer 4: External Device Modules (Symphony.ExternalDevices)
- Axopatch200B, MultiClampCommander, etc.
- Plug into core’s external‐device API to control secondary devices synchronously with DAQ
- Layer 5: Persistence
- HDF5 wrapper (HDF5DotNet + custom H5EpochPersistor) for hierarchical data storage
- XML persistence modules (legacy doc)
- Layer 6: Native Interop & Libraries
- HekaNativeInterop (P/Invoke bindings to ITCMM headers)
- HekaIOBridge (C++ DLL for cross‐language bridging)
- External third-party binaries under /externals (HDF5, ITCMM, GoogleTest)

##### Component Relationships & Data Flows
- Client apps invoke Core APIs to
- SELECT a hardware controller plugin → calls into Native Interop → hardware driver
- REQUEST data stream → Core dispatches via DAQController → returns DAQStream of IOData
- CONTROL external devices concurrently via ExternalDevices modules
- Core → HardwareController → NativeInterop → Physical Device
- Core → Persistence → HDF5 library → Disk
- Core → ExternalDevices → Device SDKs
- Client Apps → Core

##### Architectural Patterns & Design Principles
- Plugin pattern: Hardware controllers and external devices are interchangeable modules implementing interfaces.
- Layered architecture: Clear separation between core logic, hardware abstraction, persistence, and native interop.
- Dependency inversion: Core depends on interfaces (IHardwareController, IEpochPersistor) not concrete implementations.
- Adapter/Bridge: Native interop projects adapt unmanaged APIs (ITCMM, NIDAQ) to .NET types.

##### Details to Capture
- Interfaces and key classes in Core: IHardwareController, DAQStream, Epoch, IEpochPersistor
- How controller plugins implement these interfaces and rely on native layers.
- The use of HDF5DotNet underpinnings in Persistence.
- ExternalDevices module hooking into Core’s device‐control API.
- Test coverage: IntegrationTests sitting atop controllers/core.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: Client Applications & Tools
    subgraph "Layer 1: Client Applications & Tools"
        direction TB
        MT["MessageTrapper"]:::client
        HS["HekaSandbox"]:::client
        Installer["Installer"]:::client
    end

    %% Layer 2: Core Framework
    subgraph "Layer 2: Core Framework"
        direction TB
        Core["Symphony.Core"]:::core
        IHC["IHardwareController"]:::core
        DS["DAQStream"]:::core
        Epoch["Epoch"]:::core
        Meas["Measurement"]:::core
        IEP["IEpochPersistor"]:::core
        H5EP["H5EpochPersistor"]:::core
    end

    %% Layer 3: Hardware Controller Plugins
    subgraph "Layer 3: Hardware Controller Plugins"
        direction TB
        HekaCtrl["HekaDAQController"]:::hardware
        NI["NIDAQController"]:::hardware
        Sim["SimulationDAQController"]:::hardware
    end

    %% Layer 4: External Device Modules
    subgraph "Layer 4: External Device Modules"
        direction TB
        ExtCore["Symphony.ExternalDevices"]:::external
        Axo["Axopatch200B"]:::external
        Multi["MultiClampCommander"]:::external
    end

    %% Layer 5: Persistence
    subgraph "Layer 5: Persistence"
        direction TB
        HDF5Proj["HDF5 Wrapper (HDF5.csproj)"]:::persistence
        H5API["H5File/H5Group/H5Dataset"]:::persistence
        Disk[/"HDF5 File Storage"/]:::persistence
    end

    %% Layer 6: Native Interop & Libraries
    subgraph "Layer 6: Native Interop & Libraries"
        direction TB
        HekaNI["HekaNativeInterop"]:::interop
        Bridge["HekaIOBridge"]:::interop
        HekkaNative["HekkaNative C++"]:::interop
        Externals["externals (ITCMM, HDF5, HDF5DotNet)"]:::interop
    end

    %% Data & Control Flows
    MT -->|uses API| Core
    HS -->|uses API| Core
    Installer -->|deploys| Core

    Core -->|implements| IHC
    Core -->|provides| DS
    Core -->|provides| Epoch
    Core -->|provides| Meas
    Core -->|depends on| IEP
    Core -->|instantiates| H5EP

    Core -->|selects| HekaCtrl
    Core -->|selects| NI
    Core -->|selects| Sim

    HekaCtrl -->|P/Invoke| HekaNI
    NI -->|platform invoke| HekaNI
    Sim -->|simulates IO| Externals

    HekaNI -->|calls| HekkaNative
    Bridge -->|bridges| HekkaNative
    Externals ---|build dep| HekaNI
    Externals ---|build dep| Bridge
    Externals ---|build dep| HekkaNative

    Core -->|controls| ExtCore
    ExtCore -->|manages| Axo
    ExtCore -->|manages| Multi
    Axo -->|interop| Externals
    Multi -->|interop| Externals

    Core -->|persists| HDF5Proj
    HDF5Proj -->|uses| H5API
    H5API -->|writes| Disk
    Externals ---|provides| H5API

    %% Click Events - Client
    click MT "https://github.com/symphony-das/symphony-core/blob/master/src/symphony-core/MessageTrapper/MessageTrapper.csproj"
    click HS "https://github.com/symphony-das/symphony-core/blob/master/src/symphony-core/HekaSandbox/HekaSandbox.csproj"
    click Installer "https://github.com/symphony-das/symphony-core/blob/master/src/symphony-core/Setup/Setup.wixproj"

    %% Click Events - Core
    click Core "https://github.com/symphony-das/symphony-core/blob/master/src/symphony-core/Symphony.Core/Symphony.Core.csproj"
    click IHC "https://github.com/symphony-das/symphony-core/blob/master/src/symphony-core/Symphony.Core/IHardwareController.cs"
    click DS "https://github.com/symphony-das/symphony-core/blob/master/src/symphony-core/Symphony.Core/DAQStream.cs"
    click Epoch "https://github.com/symphony-das/symphony-core/blob/master/src/symphony-core/Symphony.Core/Epoch.cs"
    click Meas "https://github.com/symphony-das/symphony-core/blob/master/src/symphony-core/Symphony.Core/Measurement.cs"
    click IEP "https://github.com/symphony-das/symphony-core/blob/master/src/symphony-core/Symphony.Core/IEpochPersistor.cs"
    click H5EP "https://github.com/symphony-das/symphony-core/blob/master/src/symphony-core/Symphony.Core/H5EpochPersistor.cs"

    %% Click Events - Hardware Plugins
    click HekaCtrl "https://github.com/symphony-das/symphony-core/blob/master/src/symphony-core/HekaDAQController/HekaDAQController.csproj"
    click NI "https://github.com/symphony-das/symphony-core/blob/master/src/symphony-core/NIDAQController/NIDAQController.csproj"
    click Sim "https://github.com/symphony-das/symphony-core/blob/master/src/symphony-core/SimulationDAQController/Symphony.SimulationDAQController.csproj"

    %% Click Events - External Devices
    click ExtCore "https://github.com/symphony-das/symphony-core/blob/master/src/symphony-core/Symphony.ExternalDevices/Symphony.ExternalDevices.csproj"
    click Axo "https://github.com/symphony-das/symphony-core/blob/master/src/symphony-core/Symphony.ExternalDevices/Axopatch200B.cs"
    click Multi "https://github.com/symphony-das/symphony-core/blob/master/src/symphony-core/Symphony.ExternalDevices/MultiClampCommander.cs"

    %% Click Events - Persistence
    click HDF5Proj "https://github.com/symphony-das/symphony-core/blob/master/src/symphony-core/HDF5/HDF5.csproj"

    %% Click Events - Native Interop
    click HekaNI "https://github.com/symphony-das/symphony-core/blob/master/src/symphony-core/HekaNativeInterop/HekaNativeInterop.csproj"
    click Bridge "https://github.com/symphony-das/symphony-core/blob/master/src/symphony-core/HekaIOBridge/HekaIOBridge.vcxproj"
    click HekkaNative "https://github.com/symphony-das/symphony-core/blob/master/src/symphony-core/HekkaNative/HekkaNative.vcxproj"

    %% Styles
    classDef client fill:#ffff99,stroke:#333,stroke-width:1px
    classDef core fill:#add8e6,stroke:#333,stroke-width:1px
    classDef hardware fill:#90ee90,stroke:#333,stroke-width:1px
    classDef external fill:#f0e68c,stroke:#333,stroke-width:1px
    classDef persistence fill:#dda0dd,stroke:#333,stroke-width:1px
    classDef interop fill:#ffa500,stroke:#333,stroke-width:1px
```
