# goneuralai/neural-subnet architecture

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

- Interactive diagram: https://gitdiagram.com/goneuralai/neural-subnet
- Repository: https://github.com/goneuralai/neural-subnet

## Overview

##### Main Components

- Miner Subsystem – Separate out components responsible for:
- The “miner” functionality (found in directories such as neurons, neuralai/miner, and parts of neuralai/base).
- Components that receive input (text or image prompts) to generate a 3D mesh.
- PM2-managed services for running miner processes.

- Validator Subsystem – Detail the validator components:
- Modules found in neuralai/validator and the dedicated “validation” directory.
- The process flow where validators assign tasks, receive 3D mesh outputs from miners, generate rendered views, and evaluate quality (e.g., using similarity models like CLIP).

- Inference and Generation Pipelines – Highlight the “generate” directory which holds:
- Several inference pipelines (“infer”, “mvd”, “svrm”) that transform inputs (text/image) into 3D assets.
- Scripts that run end-to-end pipelines (for example, the various shell scripts for quick demos or fast runs).
- Asset generation endpoints (e.g., generate/serve.py) that serve 3D model generation.

- API and Integration Layers – Include the “neuralai/api” components that may expose endpoints or interfaces for interaction with the rest of the subnet or external clients.

- CI/CD and Deployment – Note directories like .circleci and script files (e.g., run.sh, setup.py) that assist in deployment and continuous integration.

##### Relationships and Data Flows

- Data Flow between Validators and Miners:

- Inference Pipeline Integration:
- Link the Inference Pipelines (under generate/infer, generate/mvd, and generate/svrm) to both the Miner and API endpoints. These pipelines are responsible for the transformation processes used by miners.
- That these pipelines may be invoked both directly (via command line scripts) and indirectly through service orchestration (via PM2-managed processes).

- External Dependencies and Tools:
- Integration points with external services such as Hugging Face (for model downloads), Anthropic’s Claude (for image-to-text functions in validators), and possibly the underlying Bittensor network.

##### Architectural Patterns and Design Principles

- Modular and Microservice-like Design:
- Miners, validators, and pipeline modules as distinct microservices or modules.
- Loose coupling between generators (miners) and evaluators (validators), which exchange work over well-defined channels.

- Extensibility and Interconnection:
- Points of extensibility (for example, additional generation scripts or future integration with enhanced validators) by showing clear data flow and feedback loops.

- Real-Time and Parallel Processing:

- CI/CD and Automation:

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Overall System Node
    NS["NeuralAI Subnet"]:::overall

    %% Miner Subsystem
    subgraph MinerSubsystem["Miner Subsystem"]
        direction TB
        M_Function["Miner Functionality"]:::miner
        M_PM2["Process Management (PM2 & run.sh)"]:::miner
    end

    %% Validator Subsystem
    subgraph ValidatorSubsystem["Validator Subsystem"]
        direction TB
        V_Main["Validator Components"]:::validator
        V_Dedicated["Dedicated Validation"]:::validator
    end

    %% Inference & Generation Pipelines
    subgraph InferencePipelines["Inference & Generation Pipelines"]
        direction TB
        IG_Infer["Inference Pipelines"]:::inference
        IG_MVD["MVD Pipeline"]:::inference
        IG_SVRM["SVRM Pipeline"]:::inference
        IG_Endpoint["Asset Generation Endpoint"]:::inference
        IG_Scripts["Demo/Fast Run Scripts"]:::inference
    end

    %% API & Integration Layers
    subgraph APIIntegration["API & Integration"]
        direction TB
        API["API Endpoints"]:::api
    end

    %% CI/CD & Deployment
    subgraph CICDDeployment["CI/CD & Deployment"]
        direction TB
        CICD["CI/CD & Deployment Scripts"]:::cicd
    end

    %% External Dependencies
    HF["Hugging Face"]:::external
    AC["Anthropic Claude"]:::external
    BN["Bittensor Network"]:::external

    %% Inclusion relationships from Overall System
    NS --> M_Function
    NS --> V_Main
    NS --> IG_Infer
    NS --> API
    NS --> CICD

    %% Data Flow between Validators and Miners
    V_Main -->|"prompts"| M_Function
    M_Function -->|"3DModels"| V_Main

    %% Inference Pipeline Integration
    IG_Infer -->|"invokes"| M_Function
    IG_MVD  -->|"invokes"| M_Function
    IG_SVRM -->|"invokes"| M_Function
    IG_Endpoint -->|"feeds"| API
    IG_Scripts -->|"triggers"| IG_Endpoint

    %% External Dependencies interactions
    HF -->|"modelDownloads"| M_Function
    AC -->|"image-to-text"| V_Dedicated
    BN -->|"subnetIntegration"| M_Function

    %% CI/CD Deployment flows
    CICD -->|"deploys"| M_Function
    CICD -->|"deploys"| V_Main
    CICD -->|"deploys"| IG_Infer
    CICD -->|"deploys"| API

    %% Click Events for Component Mapping
    click NS "https://github.com/goneuralai/neural-subnet/blob/main/README.md"
    click NS "https://github.com/goneuralai/neural-subnet/blob/main/neuralai/__init__.py"

    click M_Function "https://github.com/goneuralai/neural-subnet/blob/main/neurons/miner.py"
    click M_Function "https://github.com/goneuralai/neural-subnet/tree/main/neuralai/miner/"
    click M_Function "https://github.com/goneuralai/neural-subnet/blob/main/neuralai/base/miner.py"
    click M_PM2 "https://github.com/goneuralai/neural-subnet/blob/main/run.sh"

    click V_Main "https://github.com/goneuralai/neural-subnet/blob/main/neuralai/validator/miner_manager.py"
    click V_Main "https://github.com/goneuralai/neural-subnet/blob/main/neuralai/validator/forward.py"
    click V_Dedicated "https://github.com/goneuralai/neural-subnet/blob/main/validation/rendering.py"
    click V_Dedicated "https://github.com/goneuralai/neural-subnet/blob/main/validation/claude_integration.py"
    click V_Dedicated "https://github.com/goneuralai/neural-subnet/tree/main/validation/validation/"

    click IG_Infer "https://github.com/goneuralai/neural-subnet/tree/main/generate/infer/"
    click IG_MVD "https://github.com/goneuralai/neural-subnet/tree/main/generate/mvd/"
    click IG_SVRM "https://github.com/goneuralai/neural-subnet/tree/main/generate/svrm/"
    click IG_Endpoint "https://github.com/goneuralai/neural-subnet/blob/main/generate/serve.py"
    click IG_Scripts "https://github.com/goneuralai/neural-subnet/tree/main/generate/scripts/"

    click API "https://github.com/goneuralai/neural-subnet/tree/main/neuralai/api/"

    click CICD "https://github.com/goneuralai/neural-subnet/blob/main/.circleci/config.yml"
    click CICD "https://github.com/goneuralai/neural-subnet/blob/main/run.sh"
    click CICD "https://github.com/goneuralai/neural-subnet/blob/main/setup.py"
    click CICD "https://github.com/goneuralai/neural-subnet/blob/main/scripts/install_staging.sh"

    %% Styles
    classDef overall fill:#f9e79f,stroke:#d68910,stroke-width:2px;
    classDef miner fill:#a9cce3,stroke:#2471a3,stroke-width:2px;
    classDef validator fill:#abebc6,stroke:#239b56,stroke-width:2px;
    classDef inference fill:#f9e79f,stroke:#d68910,stroke-width:2px;
    classDef api fill:#fcf3cf,stroke:#b7950b,stroke-width:2px;
    classDef cicd fill:#f5b7b1,stroke:#cb4335,stroke-width:2px;
    classDef external fill:#d5dbdb,stroke:#636e72,stroke-dasharray: 5 5,stroke-width:2px;
```
