# mode-network/synth-subnet architecture

> Architecture diagram of the GitHub repository mode-network/synth-subnet, 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/mode-network/synth-subnet
- Repository: https://github.com/mode-network/synth-subnet

## Overview

##### Main Components

- Miners: Represented by code in directories such as synth/miner, neurons/miner, and miner.config*. They’re responsible for generating multiple simulated price paths per prompt.
- Validators: Implemented in synth/validator and neurons/validator. They receive miner predictions, validate them, calculate CRPS scores (and additional moving average/softmax calculations), and then determine leaderboard scores and emissions.
- API Layer: Located under synth/api; this layer exposes endpoints for receiving inputs, distributing prompts to miners, and handling miner responses.
- Business Logic & Simulation Engine: The core simulation and scoring functions reside in the synth/base, synth/simulation_input, and associated utility modules. This encapsulates forecast generation, the CRPS scoring algorithm, and the moving-average leaderboarding.
- Database Layer: The synth/db folder (along with Alembic migrations in the alembic folder) shows that the application persists historical predictions, scores, and configuration data.
- External Integrations:
- Pyth Oracle: Used by both miners and validators to obtain real price data at a given start time.
- Bittensor Network: The computed final weights are sent over to Bittensor.
- Auxiliary Modules:
- “dca” and “neurons” provide supplementary services which may handle staking, additional prediction utilities, or other data processing.
- “verify” likely represents scripts used for supplementary verification of predictions or permits.
- Infrastructure & Deployment: Dockerfile(s), docker-compose.yaml, and CI/CD configurations (.github/workflows) indicate containerized deployment and automated testing/integration practices.

##### Relationships and Interactions

- The Validator sends a request (with input prompts detailing parameters such as asset, start_time, time_increment, etc.) to a Miner.
- The Miner generates predictions (an ensemble of price paths) and sends them back.
- The Validator then runs its own validation functions. In case of errors, it stores error logs; otherwise, it stores the validated results in the Database (or “Storage”).
- Post-processing includes retrieving past scores, applying an exponentially decaying time-weighted average, performing softmax normalization, and finally sending the final emission weights to Bittensor.
- External Price Provider (Pyth Oracle) and the Bittensor network with clear one-way and two-way communications where applicable.

##### Architectural Patterns and Design Principles

- Layered Architecture: Different layers (API, business logic, database, external services) are separated, which eases maintenance and scalability.
- Microservice-ish Interaction: Although all within one repository, components are modular (miners, validators, API, database) and communicate via clear interfaces.
- Containerization & CI/CD: With Dockerfiles, docker-compose, and GitHub workflows, the project emphasizes reproducible environments and continuous integration.

##### Technologies & Frameworks

- Python: The primary language for simulation, scoring, and backend logic.
- NodeJS: Evident from the miner/validator config JavaScript files and PM2 process manager.
- Docker: For containerization.
- Alembic & SQLAlchemy (implied by folder names and migration files): For database schema management.
- Rust & pkg-config: For any performance-critical parts or additional tooling.
- External dependency integration (Pyth Oracle and Bittensor).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal Components
    API["API Layer"]:::internal
    Validator["Validators"]:::internal
    Miners["Miners"]:::internal
    Business["Simulation Engine/Business Logic"]:::internal
    Database["Database"]:::internal
    Auxiliary["Auxiliary Modules"]:::internal

    %% External Services
    Oracle["Pyth Price Oracle"]:::external
    Bittensor["Bittensor Network"]:::external

    %% Infrastructure & Deployment (support)
    Infrastructure["Infrastructure & Deployment"]:::infra

    %% Flow Connections
    API -->|"trigger_prompt"| Validator
    Validator -->|"request_with_input_prompts"| Miners
    Miners -->|"return_prediction_ensemble"| Validator
    Validator -->|"compute_CRPS"| Business
    Business -->|"return_scored_data"| Validator
    Validator -->|"store_scores"| Database
    Validator -->|"call_price_data"| Oracle
    Validator -->|"send_final_weights"| Bittensor

    %% Supporting dependencies
    Validator ---|"utilizes"| Auxiliary
    Business ---|"leverages"| Infrastructure

    %% Click Events for Miners
    click Miners "https://github.com/mode-network/synth-subnet/tree/main/synth/miner"
    click Miners "https://github.com/mode-network/synth-subnet/blob/main/neurons/miner.py"
    click Miners "https://github.com/mode-network/synth-subnet/blob/main/miner.config.js"
    click Miners "https://github.com/mode-network/synth-subnet/blob/main/miner.dev.config.js"
    click Miners "https://github.com/mode-network/synth-subnet/blob/main/miner.test.config.js"

    %% Click Events for Validators
    click Validator "https://github.com/mode-network/synth-subnet/tree/main/synth/validator"
    click Validator "https://github.com/mode-network/synth-subnet/blob/main/neurons/validator.py"

    %% Click Events for API Layer
    click API "https://github.com/mode-network/synth-subnet/tree/main/synth/api"

    %% Click Events for Simulation Engine & Business Logic
    click Business "https://github.com/mode-network/synth-subnet/tree/main/synth/base"
    click Business "https://github.com/mode-network/synth-subnet/blob/main/synth/simulation_input.py"

    %% Click Events for Database Layer
    click Database "https://github.com/mode-network/synth-subnet/tree/main/synth/db"
    click Database "https://github.com/mode-network/synth-subnet/tree/main/alembic"

    %% Click Event for External Price Oracle
    click Oracle "https://github.com/mode-network/synth-subnet/blob/main/synth/validator/price_data_provider.py"

    %% Click Events for Infrastructure & Deployment
    click Infrastructure "https://github.com/mode-network/synth-subnet/tree/main/Dockerfile"
    click Infrastructure "https://github.com/mode-network/synth-subnet/blob/main/docker-compose.yaml"
    click Infrastructure "https://github.com/mode-network/synth-subnet/tree/main/.github/workflows"

    %% Click Events for Auxiliary Modules
    click Auxiliary "https://github.com/mode-network/synth-subnet/tree/main/dca"
    click Auxiliary "https://github.com/mode-network/synth-subnet/tree/main/verify"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef external fill:#FFE4B5,stroke:#000,stroke-width:1px;
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
