# neuracoreai/neuracore architecture

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

- Interactive diagram: https://gitdiagram.com/neuracoreai/neuracore
- Repository: https://github.com/neuracoreai/neuracore

## Overview

##### Project type and purpose
- This is an open-source Python client library/SDK (“Neuracore Python Client”) plus training infrastructure for robotics data collection, streaming, and ML model development/deployment.
- It provides:
- A CLI layer (commands like nc-login, nc-launch-server, neuracore-validate)
- An API client for interacting with the Neuracore SaaS platform (HTTP/REST, SSE, P2P streaming)
- Core abstractions for robots, datasets, recording, streaming, and CLI utilities
- A modular ML training subsystem (Hydra configurations, PyTorch DDP, built-in algorithms, custom-algorithm plugin API)

##### File structure
- Top-level directories:
- neuracore/api: HTTP client, endpoints, datasets, training, logging
- neuracore/core: authentication, config manager, CLI commands, data/streaming abstractions, utilities
- neuracore/ml: training entrypoint, config/, algorithms/, datasets/, trainers/, utils/
- dataset_upload_scripts: standalone scripts for bulk dataset upload
- examples/: code samples (Python, ROS/Docker) demonstrating usage
- tests/: unit & integration tests
- Config & build: setup.py, cSpell.json, .github CI/deploy workflows, pre-commit, CHANGELOG, LICENSE
- Patterns:
- Layered architecture (CLI → core → api)
- Plugin pattern for algorithms (dynamic discovery via algorithm_utils)
- Hydra for config composition in training
- Streaming pipelines (SSE, P2P) modularized under core/streaming

##### Key insights from README
- High-level flow: user authenticates → connects to robot → logs data (joint states, images, language) → streams to SaaS or local endpoint → trains models (local or cloud) → deploys inference endpoints
- Supported technologies: URDF, MuJoCo, PyTorch, Hydra, SSE, custom data types
- CLI tools provide entrypoints into core functionality

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer" 
        CLI["CLI Layer\n(neuracore.core.cli)"]:::internal
    end
    click CLI "https://github.com/neuracoreai/neuracore/tree/main/neuracore/core/cli/"

    %% Core Services
    subgraph "Core Services" 
        Auth["Authentication Service\n(neuracore/core/auth.py)"]:::internal
        Config["Configuration Manager\n(neuracore/core/config/config_manager.py)"]:::internal
        Data["Core Data Abstractions\n(neuracore/core/data/)"]:::internal
        EndpointDefs["Endpoint Definitions\n(neuracore/core/endpoint.py)"]:::internal
        Orgs["Organization Management\n(neuracore/core/organizations.py)"]:::internal
        RobotUtils["Robot Interface Utilities\n(neuracore/core/robot.py)"]:::internal
        Utils["Core Utilities\n(neuracore/core/utils/)"]:::internal
    end
    click Auth "https://github.com/neuracoreai/neuracore/blob/main/neuracore/core/auth.py"
    click Config "https://github.com/neuracoreai/neuracore/blob/main/neuracore/core/config/config_manager.py"
    click Data "https://github.com/neuracoreai/neuracore/tree/main/neuracore/core/data/"
    click EndpointDefs "https://github.com/neuracoreai/neuracore/blob/main/neuracore/core/endpoint.py"
    click Orgs "https://github.com/neuracoreai/neuracore/blob/main/neuracore/core/organizations.py"
    click RobotUtils "https://github.com/neuracoreai/neuracore/blob/main/neuracore/core/robot.py"
    click Utils "https://github.com/neuracoreai/neuracore/tree/main/neuracore/core/utils/"

    %% API Client
    subgraph "API Client" 
        API_Core["core.py"]:::internal
        API_Datasets["datasets.py"]:::internal
        API_Endpoints["endpoints.py"]:::internal
        API_Logging["logging.py"]:::internal
        API_Training["training.py"]:::internal
    end
    click API_Core "https://github.com/neuracoreai/neuracore/blob/main/neuracore/api/core.py"
    click API_Datasets "https://github.com/neuracoreai/neuracore/blob/main/neuracore/api/datasets.py"
    click API_Endpoints "https://github.com/neuracoreai/neuracore/blob/main/neuracore/api/endpoints.py"
    click API_Logging "https://github.com/neuracoreai/neuracore/blob/main/neuracore/api/logging.py"
    click API_Training "https://github.com/neuracoreai/neuracore/blob/main/neuracore/api/training.py"

    %% Streaming Subsystem
    subgraph "Streaming Subsystem" 
        SSE["SSE Consumer\n(neuracore/core/streaming/base_sse_consumer.py)"]:::internal
        EventLoop["Event Loop Utils\n(event_loop_utils.py)"]:::internal
        DataStream["Data Stream\n(neuracore/core/streaming/data_stream.py)"]:::internal
        Bucket["Bucket Uploaders\n(neuracore/core/streaming/bucket_uploaders/)"]:::internal
        P2P["P2P Subsystem\n(neuracore/core/streaming/p2p/)"]:::internal
        RecState["Recording State Manager\n(neuracore/core/streaming/recording_state_manager.py)"]:::internal
    end
    click SSE "https://github.com/neuracoreai/neuracore/blob/main/neuracore/core/streaming/base_sse_consumer.py"
    click EventLoop "https://github.com/neuracoreai/neuracore/blob/main/neuracore/core/streaming/event_loop_utils.py"
    click DataStream "https://github.com/neuracoreai/neuracore/blob/main/neuracore/core/streaming/data_stream.py"
    click Bucket "https://github.com/neuracoreai/neuracore/tree/main/neuracore/core/streaming/bucket_uploaders/"
    click P2P "https://github.com/neuracoreai/neuracore/tree/main/neuracore/core/streaming/p2p/"
    click RecState "https://github.com/neuracoreai/neuracore/blob/main/neuracore/core/streaming/recording_state_manager.py"

    %% ML Training Subsystem
    subgraph "ML Training Subsystem"
        TrainEntrypoint["Training Entrypoint\n(neuracore/ml/train.py)"]:::internal
        HydraCfg["Hydra Config Modules\n(neuracore/ml/config/)"]:::internal
        AlgoPlugins["Algorithm Plugins\n(neuracore/ml/algorithms/)"]:::plugin
        AlgoUtils["Algorithm Discovery Utils\n(neuracore/ml/algorithm_utils/modules.py)"]:::plugin
        DataAdapters["Dataset Adapters\n(neuracore/ml/datasets/)"]:::internal
        Trainers["Training Orchestrators\n(neuracore/ml/trainers/)"]:::internal
        MLLogging["Training Logging\n(neuracore/ml/logging/)"]:::internal
        MLUtils["ML Utilities\n(neuracore/ml/utils/)"]:::internal
    end
    click TrainEntrypoint "https://github.com/neuracoreai/neuracore/blob/main/neuracore/ml/train.py"
    click HydraCfg "https://github.com/neuracoreai/neuracore/tree/main/neuracore/ml/config/"
    click AlgoPlugins "https://github.com/neuracoreai/neuracore/tree/main/neuracore/ml/algorithms/"
    click AlgoUtils "https://github.com/neuracoreai/neuracore/blob/main/neuracore/ml/algorithm_utils/modules.py"
    click DataAdapters "https://github.com/neuracoreai/neuracore/tree/main/neuracore/ml/datasets/"
    click Trainers "https://github.com/neuracoreai/neuracore/tree/main/neuracore/ml/trainers/"
    click MLLogging "https://github.com/neuracoreai/neuracore/tree/main/neuracore/ml/logging/"
    click MLUtils "https://github.com/neuracoreai/neuracore/tree/main/neuracore/ml/utils/"

    %% External Services
    subgraph "External Services" 
        SaaS["Neuracore SaaS API\n(HTTPS)"]:::external
        Storage["Object Storage\n(S3/GCS)"]:::external
        RemoteInf["Remote Inference Endpoint"]:::external
        LocalPolicy["Local Policy Server"]:::external
        RobotSim["Robot Simulator/Hardware"]:::external
    end

    %% Scripts and Examples
    subgraph "Scripts & Examples" 
        UploadScripts["Dataset Upload Scripts\n(dataset_upload_scripts/)"]:::scripts
        PythonEx["Python Examples\n(examples/*.py)"]:::scripts
        ROSEx["ROS/Docker Examples\n(examples/ros_example/)"]:::scripts
    end
    click UploadScripts "https://github.com/neuracoreai/neuracore/tree/main/dataset_upload_scripts/"
    click PythonEx "https://github.com/neuracoreai/neuracore/tree/main/examples/"
    click ROSEx "https://github.com/neuracoreai/neuracore/tree/main/examples/ros_example/"

    %% Connections
    CLI -->|"invokes"| Auth
    CLI --> Config
    CLI --> Data
    CLI --> EndpointDefs
    Auth --> API_Endpoints
    Config --> API_Core
    Data --> API_Datasets
    EndpointDefs --> API_Endpoints
    API_Core -->|HTTP| SaaS
    API_Datasets -->|HTTP| SaaS
    API_Logging --> MLLogging
    API_Training --> MLLogging

    Data --> SSE
    DataStream --> Bucket
    Data --> P2P
    P2P --> RecState
    SSE --> SaaS
    Bucket --> Storage
    P2P -->|"P2P"| RemoteInf

    UploadScripts --> API_Datasets
    PythonEx --> CLI
    ROSEx --> CLI

    TrainEntrypoint --> HydraCfg
    TrainEntrypoint --> AlgoUtils
    HydraCfg --> AlgoPlugins
    TrainEntrypoint --> DataAdapters
    DataAdapters --> Trainers
    Trainers --> MLLogging
    Trainers -->|"PyTorch DDP"| RemoteInf
    MLUtils --> Trainers

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef external fill:#E8F6D0,stroke:#28a745,color:#28a745
    classDef plugin fill:#FFEFD0,stroke:#FF8C00,color:#FF8C00
    classDef scripts fill:#F0F0F0,stroke:#666666,color:#666666
```
