# mwasifanwar/biosignal-ai architecture

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

- Interactive diagram: https://gitdiagram.com/mwasifanwar/biosignal-ai
- Repository: https://github.com/mwasifanwar/biosignal-ai

## Overview

##### Project Type and Purpose
- Project type: a full-stack, Python-based machine-learning inference and API service for interpreting EEG/fMRI signals.
- Purpose: ingest biosignals, preprocess them, run decoding models (traditional and deep learning), expose results via a REST API, and drive external devices or diagnostics.

##### File Structure
- Top-level scripts:
- main.py – likely a CLI or orchestrator for batch processing.
- run_api.py – entrypoint for the web/API service.
- setup.py, requirements.txt – packaging and dependencies.
- Directories:
- api/ – REST API layer: routing (routes.py) and middleware.
- config/ – application and model configuration (settings.py, model_config.py).
- core/ – core processing pipeline:
– bci_controller.py (interfaces to devices),
– eeg_processor.py (signal preprocessing),
– fmri_analyzer.py,
– neural_decoder.py (orchestration of model inference).
- models/ – ML components:
– traditional_models.py (classical ML),
– deep_models.py (deep-learning architectures).
- utils/ – supporting utilities:
– data_loader.py, signal_utils.py, visualization.py.
- tests/ – unit & integration tests.

##### Extract Insights from README
- Key functions: control devices, predict disorders, enable BCI.
- Core technologies implied: Python, NumPy/SciPy, ML frameworks (e.g., PyTorch/TensorFlow, scikit-learn), FastAPI (inferred from api/).

##### Main Components and Their Relationships
a. Data Inputs
– EEG sensors
– fMRI scanners
b. Data Ingestion & Preprocessing
– utils/data_loader.py loads raw signals.
– core/eeg_processor.py and core/fmri_analyzer.py clean and transform data.
c. Neural Decoding & Prediction
– core/neural_decoder.py selects model (based on config/model_config.py).
– models/traditional_models.py for classical algorithms.
– models/deep_models.py for neural nets.
d. BCI Control Layer
– core/bci_controller.py translates model outputs into device commands.
e. API Layer
– run_api.py launches the REST service.
– api/routes.py defines endpoints for:
- submitting new signal data
- retrieving predictions or control commands
– api/middleware.py handles auth, logging, error handling.
f. Configuration & Settings
– config/settings.py manages environment variables and global settings.
g. Utilities & Visualization
– utils/visualization.py for plotting results (used in dashboards or logs).

##### Architectural Patterns & Principles
- Layered architecture:
- Ingestion → Processing → Inference → Serving.
- Clear separation of concerns:
- “api” vs. “core” vs. “models” vs. “utils”.
- Config-driven behavior (model selection, hyperparameters).
- Test-driven reliability (py.test suite in tests/).

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Data Sources
    EEG["EEG Sensors"]:::external
    fMRI["fMRI Scanners"]:::external

    %% Preprocessing Layer
    Loader["Raw Signal Loader\n(utils/data_loader.py)"]:::processing
    SignalUtils["Signal Utilities\n(utils/signal_utils.py)"]:::processing
    EEGProc["EEG Preprocessor\n(core/eeg_processor.py)"]:::processing
    fMRIProc["fMRI Analyzer\n(core/fmri_analyzer.py)"]:::processing

    %% Inference Layer
    NeuralDecoder["Neural Decoder\n(core/neural_decoder.py)"]:::processing
    TraditionalModels["Traditional Models\n(models/traditional_models.py)"]:::models
    DeepModels["Deep Learning Models\n(models/deep_models.py)"]:::models

    %% Control Layer
    Controller["BCI Controller\n(core/bci_controller.py)"]:::processing

    %% API & Orchestrator
    Orchestrator["Batch Orchestrator\n(main.py)"]:::api
    runAPI["API Entrypoint\n(run_api.py)"]:::api
    Middleware["API Middleware\n(api/middleware.py)"]:::api
    Routes["API Routes\n(api/routes.py)"]:::api

    %% Configuration
    Settings["Global Settings\n(config/settings.py)"]:::config
    ModelConfig["Model Selection\n(config/model_config.py)"]:::config

    %% Utilities
    Visualization["Visualization Utilities\n(utils/visualization.py)"]:::utils

    %% Data Flow
    EEG -->|raw signal| Loader
    fMRI -->|raw signal| Loader
    Loader -->|signal array| SignalUtils
    SignalUtils -->|filtered data| EEGProc
    SignalUtils -->|transformed data| fMRIProc
    EEGProc -->|preprocessed features| NeuralDecoder
    fMRIProc -->|preprocessed features| NeuralDecoder

    %% Config to Decoder
    Settings --> NeuralDecoder
    ModelConfig --> NeuralDecoder

    %% Decoder to Models
    NeuralDecoder -->|invoke| TraditionalModels
    NeuralDecoder -->|invoke| DeepModels

    %% Decoder to Controller
    NeuralDecoder -->|predictions| Controller

    %% Controller to Devices
    Controller -->|commands| EEG
    Controller -->|commands| fMRI

    %% Batch Mode
    Orchestrator -->|batch run| Loader

    %% API Mode
    runAPI --> Middleware --> Routes
    Routes -->|sync inference| NeuralDecoder
    Routes -->|control request| Controller

    %% Visualization
    NeuralDecoder -->|results| Visualization
    Controller -->|status logs| Visualization

    %% Click Events
    click Loader "https://github.com/mwasifanwar/biosignal-ai/blob/main/utils/data_loader.py"
    click SignalUtils "https://github.com/mwasifanwar/biosignal-ai/blob/main/utils/signal_utils.py"
    click EEGProc "https://github.com/mwasifanwar/biosignal-ai/blob/main/core/eeg_processor.py"
    click fMRIProc "https://github.com/mwasifanwar/biosignal-ai/blob/main/core/fmri_analyzer.py"
    click NeuralDecoder "https://github.com/mwasifanwar/biosignal-ai/blob/main/core/neural_decoder.py"
    click TraditionalModels "https://github.com/mwasifanwar/biosignal-ai/blob/main/models/traditional_models.py"
    click DeepModels "https://github.com/mwasifanwar/biosignal-ai/blob/main/models/deep_models.py"
    click Controller "https://github.com/mwasifanwar/biosignal-ai/blob/main/core/bci_controller.py"
    click Orchestrator "https://github.com/mwasifanwar/biosignal-ai/blob/main/main.py"
    click runAPI "https://github.com/mwasifanwar/biosignal-ai/blob/main/run_api.py"
    click Middleware "https://github.com/mwasifanwar/biosignal-ai/blob/main/api/middleware.py"
    click Routes "https://github.com/mwasifanwar/biosignal-ai/blob/main/api/routes.py"
    click Settings "https://github.com/mwasifanwar/biosignal-ai/blob/main/config/settings.py"
    click ModelConfig "https://github.com/mwasifanwar/biosignal-ai/blob/main/config/model_config.py"
    click Visualization "https://github.com/mwasifanwar/biosignal-ai/blob/main/utils/visualization.py"

    %% Styling
    classDef processing fill:#D0E6FF,stroke:#0366d6,color:#000
    classDef models fill:#D5F5E3,stroke:#28a745,color:#000
    classDef api fill:#FDEBD0,stroke:#d35400,color:#000
    classDef config fill:#E5E7E9,stroke:#7f8c8d,color:#000
    classDef utils fill:#F0F0F0,stroke:#95a5a6,color:#000
    classDef external fill:#FADBD8,stroke:#c0392b,color:#000,stroke-dasharray: 5 5
```
