# capgoblin/conflux-ai architecture

> Architecture diagram of the GitHub repository capgoblin/conflux-ai, 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/capgoblin/conflux-ai
- Repository: https://github.com/capgoblin/conflux-ai

## Overview

##### Main Components
- Local Training Environment – This involves the Python modules dealing with computing technical indicators, training LSTM neural network models, and encrypting model weights. Represent this part using elements like “Local Data”, “Local Training”, and “Local Model”.
- Secure Storage & Model Upload – Captured in the Node.js portion where encrypted model weights are uploaded (with RESTful endpoints) and later retrieved. Include components such as “Node.js Server”, “Encrypted Weights”, and “Global Model Storage”.
- Model Aggregation System – Operates within the Python “models” code (main.py) that aggregates individual models using federated learning, calculates contribution scores, and produces the global AI model.
- Trading Agent – Encompasses the autonomous trading system including the trading logic implemented via a combination of the global LSTM model and Secret AI’s LLM. This part also interfaces with a Flask server and handles trade execution.
- Smart Contract Layer – Written in Rust (in the contract/ folder) and integrated with Secret.js functions in the web-app. It manages on-chain recording of model CIDs, contribution scores, and facilitates transparent profit distribution.
- Web Application/UI – The front end (Next.js in web-app) where users deposit funds, set up trading, and interact with the platform, integrating secret functions for on-chain transactions.

##### Relationships and Data Flow
- Local data is processed and models are trained locally. Once a model is trained, its encrypted weights are sent to the Node.js server, which then stores them securely.
- The global storage (maintained by the Node.js service) makes the encrypted models available for aggregation in the Python-based model aggregation system.
- The aggregated global model’s reference (CID) is recorded on-chain via the smart contract.
- The web application provides interfaces for user deposit, model registration, and profit distribution. It communicates with smart contracts (using Secret.js functions) to record trader contributions.
- The autonomous trading agent uses the analytic model to process market data, generate trading decisions, and execute trades. Feedback (including executed trade logs) is reported back through both the Flask server and web UI.
- All these interactions follow a trustless flow, ensuring data privacy and a fair, decentralized profit-sharing mechanism.

##### Architectural Patterns & Design Principles
- Privacy-First: Emphasize that raw data never leaves the local environment; only encrypted model weights are transmitted.
- Federated Learning: Showcase how multiple models are aggregated to form a robust global model with fair attribution.
- Decoupled Services: The system clearly separates the frontend (Next.js web app), backend APIs (Node.js), computational aggregation & agent logic (Python), and smart contracts (Rust).
- Modular Interfaces: Use clear RESTful interactions (data upload/retrieval) and smart contract interactions to highlight the decoupling between secure storage, computation, and on-chain recording.

##### Relevant Technologies
- Python for data processing and model training (with requirements like PyTorch).
- Node.js (JavaScript/TypeScript) for handling API requests and secure file storage (with integrations for Autonomys AutoDrive).
- Rust for smart contract development on the Secret Network.
- Next.js (React/TypeScript) for the frontend web application and user interactions.
- Flask server as part of the trading agent’s operational backbone.
- Secret.js for blockchain/smart contract interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Local Training Environment"
        L1["Local Data & Training"]:::local
    end

    subgraph "Secure Storage & Model Upload"
        N1["Node.js Server"]:::backend
        N2["Encrypted Weights Storage"]:::backend
    end

    subgraph "Model Aggregation System"
        P1["Model Aggregator (models/main.py)"]:::aggregation
    end

    subgraph "Smart Contract Layer"
        SC1["Smart Contracts (Rust)"]:::contract
    end

    subgraph "Trading Agent"
        TA1["Trading Agent (Autonomous)"]:::trading
        TA2["Flask Server"]:::trading
    end

    subgraph "Web Application/UI"
        UI1["Web UI (Next.js)"]:::frontend
        UI2["Secret.js Interface"]:::frontend
    end

    %% Data Flow
    L1 -->|"EncryptedModelUpload"| N1
    N1 -->|"StoreWeights"| N2
    N2 -->|"WeightsRetrieval"| P1
    P1 -->|"GlobalModelCID"| SC1
    P1 -->|"GlobalModelUpdate"| TA1
    SC1 -->|"OnChainRegistration"| TA1
    TA1 -->|"TradeExecutionLog"| TA2
    TA1 -->|"TradeFeedback"| UI1
    UI1 -->|"UserDeposits&Transactions"| SC1
    UI2 -->|"SmartContractCalls"| SC1

    %% Click Events for Local Training Environment
    click L1 "https://github.com/capgoblin/conflux-ai/blob/main/models/agent.py"
    click L1 "https://github.com/capgoblin/conflux-ai/blob/main/models/src/model.py"
    click L1 "https://github.com/capgoblin/conflux-ai/blob/main/models/requirements.txt"

    %% Click Events for Secure Storage & Model Upload
    click N1 "https://github.com/capgoblin/conflux-ai/blob/main/nodejs/src/index.ts"
    click N2 "https://github.com/capgoblin/conflux-ai/tree/main/nodejs/uploads/"

    %% Click Event for Model Aggregation System
    click P1 "https://github.com/capgoblin/conflux-ai/blob/main/models/main.py"

    %% Click Events for Trading Agent
    click TA1 "https://github.com/capgoblin/conflux-ai/blob/main/models/agent.py"
    click TA1 "https://github.com/capgoblin/conflux-ai/blob/main/models/server.py"

    %% Click Event for Smart Contract Layer
    click SC1 "https://github.com/capgoblin/conflux-ai/blob/main/contract/src/contract.rs"

    %% Click Events for Web Application/UI
    click UI1 "https://github.com/capgoblin/conflux-ai/tree/main/web-app/app"
    click UI2 "https://github.com/capgoblin/conflux-ai/tree/main/web-app/components"

    %% Styles
    classDef local fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef aggregation fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef contract fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef trading fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef frontend fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
```
