# universumx/universum architecture

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

- Interactive diagram: https://gitdiagram.com/universumx/universum
- Repository: https://github.com/universumx/universum

## Overview

##### Project Type and Core Purpose
- The project is a research-driven, real-time predictive system that integrates advanced data collection from an 8-channel BCI (EEG) with sophisticated preprocessing and machine learning techniques (including CNNs, Autoencoders, LSTM networks, and Transformers) to predict lumbar tilt perception.
- It is essentially a hybrid system with clear separation of data acquisition, preprocessing, and model development components.

##### Analyzing the File Structure
- The project is divided into two main directories: “DataCollection” and “ModelDevelopment.”
- The DataCollection directory handles the ingestion, organization, and preliminary processing of raw data. It contains:
- Assets (audio files that may be used for synchronization or stimulus purposes).
- A deep hierarchical “data” folder structure where raw EEG, accelerometer, and action data are stored, along with supporting files like “subject_info.csv.”
- Modules and scripts (e.g., “data_collection.py,” “data_visualization.py,” and additional modules for local storage or influx data integration).
- Supplementary components such as a GUI (“gui.py”) and procedural documentation (“procedure.md”).
- The ModelDevelopment directory focuses on building the predictive models and processing pipelines. It includes:
- Scripts for preprocessing (e.g., “preprocessing.py”), real-time processing (e.g., “realtime.py”), and analyses (e.g., “psd3.py,” “dimension_reduction_visualizations.py”).
- Additional utility scripts (like “echo”) and raw EEG data files for initial testing.
- Also, configuration and workflow files within .github and project-level files (like README.md and Roadmap) provide context on deployment and future design iterations.

a. Main Components to Include:
- Data Ingestion and Collection Layer:
- Data sources (EEG sensors, accelerometer data, possibly pose estimation inputs from external computer vision algorithms).
- DataCollection modules (including the GUI, data_collection.py, and file assets serving as inputs/ stimuli).
- File system components with a distinction between raw data storage (EEG and accelerometer CSVs) and supplementary data (subject info, procedure documents).
- Data Preprocessing and Visualization Layer:
- Scripts for cleaning and organizing data (data_visualization.py, modules/influx_data.py, and local_storage.py).
- Preprocessing pipelines that prepare data for modeling (filtering, normalization, segmentation).
- Model Development and Evaluation Layer:
- Preprocessing utilities in the ModelDevelopment directory.
- Model building components: Autoencoders for noise reduction; LSTM/Transformer-based predictive models; and potential CNN-based pose estimation integration.
- Real-time processing modules (realtime.py) responsible for making predictions.
- Evaluation and visualization of model outputs (dimension_reduction_visualizations.py, echo, etc.).
- External Dependencies and Integration Points:
- External BCI and pose estimation systems.
- Data augmentation pipelines and potential integration points for ensemble techniques.
- Deployment pipelines (workflow configs in .github/workflows).

b. Relationships and Interactions:
- Data flow from raw EEG collection to preprocessing, feeding into the Machine Learning models.

c. Architectural Patterns and Design Principles:
- Separation of concerns: data ingestion, preprocessing, and model training/prediction are isolated components.
- Hybrid pipeline design that allows modular testing (using separate directories and components).
- Use the layered architecture approach: a bottom layer (data collection), a middle layer (data processing/preprocessing) and a top layer (model development and real-time prediction).

d. Technologies and Frameworks:
- Though the file tree does not explicitly mention external libraries, note that deep learning frameworks (TensorFlow, PyTorch), signal processing tools, and visualization libraries are implicit components.
- Mention that the project utilizes a Convolutional Neural Network for pose estimation and Autoencoders, LSTM, Transformer models for EEG data analysis.

##### Capturing Essential Architectural Elements
- Detail every major component you identified in the file tree.
- Remember to incorporate the hybrid nature of the project: it’s not only collecting data but also actively running sophisticated real-time model predictions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion and Collection Layer
    subgraph "Data Ingestion and Collection Layer"
        DC["Data Collection Module"]:::dataLayer
        GUI["GUI Module"]:::dataLayer
        Audio["Audio Stimuli Assets"]:::dataLayer
    end

    %% Raw Data Storage
    subgraph "Raw Data Storage"
        Raw["Raw Data Repository"]:::storage
    end

    %% Data Preprocessing and Visualization Layer
    subgraph "Data Preprocessing and Visualization Layer"
        Viz["Data Visualization"]:::preproc
        Influx["Influx Data Module"]:::preproc
        Local["Local Storage Module"]:::preproc
    end

    %% Model Development and Evaluation Layer
    subgraph "Model Development and Evaluation Layer"
        Preproc["Preprocessing"]:::modelDev
        Realtime["Real-time Processing"]:::modelDev
        PSD["Spectral Analysis"]:::modelDev
        DimRed["Dimension Reduction Visualization"]:::modelDev
        Echo["Utility Script (echo)"]:::modelDev
    end

    %% Deployment and Workflow Configuration
    subgraph "Deployment & Workflow Configuration"
        Workflow["Workflow Config"]:::deploy
        Readme["Project README"]:::deploy
        Roadmap["Project Roadmap"]:::deploy
    end

    %% Connections and Data Flows
    DC -->|"collects"| Raw
    Raw -->|"raw_EEG_CSV"| Viz
    Influx -->|"supplemental_data"| Viz
    Local -->|"local_data"| Viz
    Viz -->|"preprocessed_signals"| Preproc
    Preproc -->|"processed_data"| Realtime
    Realtime -->|"prediction_output"| DimRed
    Realtime -->|"real-time_feedback"| GUI
    DimRed -->|"evaluate"| Echo

    %% Click Events
    click DC "https://github.com/universumx/universum/blob/main/DataCollection/data_collection.py"
    click GUI "https://github.com/universumx/universum/blob/main/DataCollection/gui.py"
    click Audio "https://github.com/universumx/universum/tree/main/DataCollection/assets"
    click Raw "https://github.com/universumx/universum/tree/main/DataCollection/data"
    click Viz "https://github.com/universumx/universum/blob/main/DataCollection/data_visualization.py"
    click Influx "https://github.com/universumx/universum/blob/main/DataCollection/modules/influx_data.py"
    click Local "https://github.com/universumx/universum/blob/main/DataCollection/modules/local_storage.py"
    click Preproc "https://github.com/universumx/universum/blob/main/ModelDevelopment/preprocessing.py"
    click Realtime "https://github.com/universumx/universum/blob/main/ModelDevelopment/realtime.py"
    click PSD "https://github.com/universumx/universum/blob/main/ModelDevelopment/psd3.py"
    click DimRed "https://github.com/universumx/universum/blob/main/ModelDevelopment/dimension_reduction_visualizations.py"
    click Echo "https://github.com/universumx/universum/tree/main/ModelDevelopment/echo"
    click Workflow "https://github.com/universumx/universum/blob/main/.github/workflows/code_runs.yml"
    click Readme "https://github.com/universumx/universum/blob/main/README.md"
    click Roadmap "https://github.com/universumx/universum/blob/main/Roadmap/universum_prosthetic_diagram.canvas"

    %% Styles
    classDef dataLayer fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef storage fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef preproc fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef modelDev fill:#F5B7B1,stroke:#CB4335,stroke-width:2px;
    classDef deploy fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
```
