# socialtensor/socialtensorsubnet architecture

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

- Interactive diagram: https://gitdiagram.com/socialtensor/socialtensorsubnet
- Repository: https://github.com/socialtensor/socialtensorsubnet

## Overview

##### Main Components
- Decentralized Network Core: At the heart of the system are the miner and validator nodes. The README discusses their roles (validators stake TAO; miners commit GPU resources) and their participation.
- Generation Models Module: Found mainly under the “generation_models” directory. This component encapsulates model definitions, pipelines (custom pipelines, niche variants for stable diffusion, dalle, etc.), configurations, and helper utilities. This includes folders for “comfyui_helper,” “kolors,” and specialized pipelines.
- Image Generation Subnet: Under “image_generation_subnet”, which holds base and advanced logic for mining, validation, and image processing (miner, validator, protocol, utility functions like weight calculation, moderation models, etc.).
- Neurons Module: The “neurons” directory also includes miner and validator logic, which suggests an abstraction for processing “neuron” tasks across the network.
- Services: The “services” directory is broken down into several microservices that handle:
- Challenge Generating (for face, image, LLM prompt, and visual language model (vlm) tasks)
- Miner and Validator endpoints (handling API requests, processing logic)
- Rewarding mechanisms including offline rewarding and text rewarding
- Other utility services (like the “owner_api_core.py” and “rays” scripts)
- External Scripts and Configurations: Several shell scripts and configuration files (e.g., for downloading weights and setting up plugins) indicate integration points with external systems, deployment workflows, and the process manager (pm2) for service management.
- Documentation and Automation: The docs provide detailed instructions geared toward setup of both miner and validator nodes, and other workflow-specific documents (e.g., validator.md, miner.md).

##### Relationships and Interactions
- The decentralized network interacts through API endpoints – miners send image generation requests to validators (and possibly vice versa for reward verification).
- The generation_models module feeds into the image_generation_subnet and neurons modules, indicating that those components share processing pipelines.
- Services act as wrappers that expose various functionalities (e.g., prompt generating, face generating) to the network, likely communicating internally through messaging or API calls.
- Scripts and utilities play roles in initializing, downloading necessary resources (weights, plugins), and keeping services updated.

##### Architectural Patterns and Design Principles
- Microservices Architecture: The “services” folder shows that each functional part (challenge generating, miner endpoints, validator endpoints, rewarding) is separated into smaller, self-contained microservices.
- Modular Design: The separation between “generation_models”, “image_generation_subnet”, and “neurons” modules suggests a strong emphasis on reusability and scalability where core functionalities (model pipelines, image processing, validation) are implemented in a modular fashion.
- Distributed Processing: Emphasized by the decentralized network approach (miners and validators) and use of process management (via pm2) to scale GPU workloads.
- Decentralized Incentivization: The reward mechanisms and the specified formulas in the README indicate that a careful design was put into the economic model for participation.

##### Relevant Technologies, Frameworks, and Libraries
- Shell Scripts/pm2 for process management and deployment automation.
- Python as the main language (given the .py files across modules) with dependency management through requirements.txt.
- Possibly a node-based tool ecosystem for some microservices (given instructions to install NodeJS/npm) although the primary implementation seems through Python.
- External protocols like Bittensor for the decentralized aspects.

##### Final Advice
- Be detailed: Ensure you capture both the high-level network structure and the breakdown of key functionalities.

## Diagram (Mermaid)

```mermaid
flowchart TD

    subgraph "Decentralized Network Core"
        DN1["Miner (image_generation_subnet/base/miner.py)"]:::core
        DN2["Validator (image_generation_subnet/base/validator.py)"]:::core
        DN3["Neuron (image_generation_subnet/base/neuron.py)"]:::core
    end

    subgraph "Core Processing Modules"
        CP1["Generation Models (generation_models)"]:::processing
        CP2["Image Generation Subnet (image_generation_subnet)"]:::processing
        CP3["Neurons Module (neurons)"]:::processing
    end

    subgraph "Services & Endpoints"
        S1["Services (services)"]:::service
    end

    H["External Scripts & Configs"]:::utility
    I["Documentation & Automation (docs)"]:::doc

    %% Interactions between Decentralized Network and Core Processing
    DN1 -->|"ImageGenReq"| CP2
    DN2 -->|"ImageGenReq"| CP2
    DN3 -->|"ImageGenReq"| CP2
    CP2 -->|"Result/Reward"| DN2
    CP3 -->|"Result/Reward"| DN2

    %% Interactions within Core Processing Modules
    CP1 -->|"PipelineProc"| CP2
    CP1 -->|"PipelineProc"| CP3

    %% Services interactions with Decentralized Network and Core Processing
    S1 -->|"APIReq"| DN1
    S1 -->|"APIReq"| DN2
    S1 -->|"APIReq"| DN3
    S1 -->|"TriggerGen"| CP1

    %% External Scripts updating modules and services
    H -->|"Init/Update"| CP1
    H -->|"Init/Update"| S1

    %% Documentation guiding service usage
    I -->|"Guidance"| S1

    %% Styles
    classDef core fill:#a2d2ff,stroke:#000,stroke-width:1px;
    classDef processing fill:#caffbf,stroke:#000,stroke-width:1px;
    classDef service fill:#ffadad,stroke:#000,stroke-width:1px;
    classDef utility fill:#ffd6a5,stroke:#000,stroke-width:1px;
    classDef doc fill:#fdffb6,stroke:#000,stroke-width:1px;

    %% Click Events
    click DN1 "https://github.com/socialtensor/socialtensorsubnet/blob/main/image_generation_subnet/base/miner.py"
    click DN2 "https://github.com/socialtensor/socialtensorsubnet/blob/main/image_generation_subnet/base/validator.py"
    click DN3 "https://github.com/socialtensor/socialtensorsubnet/blob/main/image_generation_subnet/base/neuron.py"
    click CP1 "https://github.com/socialtensor/socialtensorsubnet/tree/main/generation_models"
    click CP2 "https://github.com/socialtensor/socialtensorsubnet/tree/main/image_generation_subnet"
    click CP3 "https://github.com/socialtensor/socialtensorsubnet/tree/main/neurons"
    click S1 "https://github.com/socialtensor/socialtensorsubnet/tree/main/services"
    click H "https://github.com/socialtensor/socialtensorsubnet/blob/main/auto_update.sh"
    click I "https://github.com/socialtensor/socialtensorsubnet/tree/main/docs"
```
