# sylvia969301/blockchain-based-federated-learning architecture

> Architecture diagram of the GitHub repository sylvia969301/blockchain-based-federated-learning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sylvia969301/blockchain-based-federated-learning
- Repository: https://github.com/sylvia969301/blockchain-based-federated-learning

## Overview

##### Project Type and Purpose
- This is a research/prototype system that combines Federated Learning (FL) with a private Ethereum-based blockchain.
- The “BCFL” directory implements federated learning using the Flower (flwr) framework; the top-level files and “geth”/“miner*” directories set up and run a private Ethereum network for model/result storage or audit.

##### File Structure
- Top Level
- BCFL/              → Federated learning code and artifacts
- geth/, miner1/, miner2/ → Private blockchain nodes (Geth directories, chaindata, keystore, genesis config)
- client_8080.py, server_8080.py, socket_client.py, socket_server.py → Simple socket-based FL demo endpoints
- requirements.txt  → Python dependencies (Flower, PyTorch, Web3 libraries)
- BCFL/flwr/
- client/           → FL client implementations (gRPC, numpy interface)
- server/           → FL server orchestrator, strategies (FedAvg, FedOpt, etc.)
- common/, dataset/ → Shared utilities, data loaders (CIFAR-10)
- proto/            → gRPC transport protobufs
- simulation/       → Ray-based simulations
- BCFL/data/           → CIFAR-10 raw data
- BCFL/aggregated_result → Folder for storing the aggregated model
- Key files: mnist_cnn.pt (model), compiled_code.json, task_owner_key (blockchain‐related keys)

##### README (empty here)
- No explicit architecture section; infer from code organization and directory names.

##### Main Components & Their Interactions
a. Federated Learning Layer
- FL Server (BCFL/flwr/server/app.py): orchestrates rounds, applies aggregation strategies
- FL Clients (BCFL/flwr/client/app.py): train on local data partitions and send model updates
- Data Store (BCFL/data/…): local datasets on each client node
- gRPC Transport (proto files + grpc_client/ in client & grpc_server/ in server): handles RPC calls
b. Blockchain Layer
- Geth Bootnode / Genesis Node (geth/, genesis.json, boot.key): the entry point of the private chain
- Miner Nodes (miner1/, miner2/): maintain blockchain, mine blocks, validate transactions
- Keystore & Keys (keystore/, task_owner_key/): accounts for submitting transactions
- Smart‐contract Interface (not explicit here—could be in client/server scripts calling Web3)
c. Control & Integration
- Orchestrator Scripts (server_8080.py, client_8080.py, socket_*.py): lightweight HTTP or socket glue
- Aggregation Export (BCFL/aggregated_result): writes final weights to a file; later submitted to blockchain
- JSON Config (compiled_code.json): possibly contains compiled smart‐contract code for deployment

##### Architectural Patterns & Principles
- Layered: clear separation between FL layer and blockchain layer
- Modular: each FL strategy in its own module; gRPC code separated from core logic
- Distributed: multiple clients and miners; uses network communication (gRPC, sockets, Ethereum P2P)
- Extensibility: strategies folder allows plugging in new aggregation rules

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Federated Learning Layer
    subgraph "Federated Learning"
        direction TB
        ServerCore["FL Server Core"]:::fl
        Strategies["Aggregation Strategies"]:::fl
        GRPCServer["gRPC Server"]:::fl
        FLServerSim["FL Simulation (Ray)"]:::fl
        AggregatedResult["Aggregated Model Output"]:::storage
        subgraph "FL Clients"
            direction TB
            FLClientCore["FL Client Core"]:::fl
            GRPCClient["gRPC Client"]:::fl
            CIFAR["CIFAR-10 Dataset"]:::storage
        end
    end

    %% Blockchain Layer
    subgraph "Blockchain Network"
        direction TB
        Bootnode["Geth Bootnode / Genesis"]:::bc
        Miner1["Miner Node 1"]:::bc
        Miner2["Miner Node 2"]:::bc
        Keystore["Keystore & Keys"]:::bc
        CompiledCode["Smart Contract Config"]:::bc
    end

    %% Orchestrators / Glue
    subgraph "Orchestrators / Glue"
        direction TB
        HTTPServer["server_8080.py"]:::external
        HTTPClient["client_8080.py"]:::external
        SocketServer["socket_server.py"]:::external
        SocketClient["socket_client.py"]:::external
    end

    %% Data & Model Flow
    ServerCore -->|"Global Model (gRPC:50051)"| FLClientCore
    FLClientCore -->|"Local Updates (gRPC:50051)"| ServerCore
    ServerCore --> AggregatedResult

    %% Blockchain Transactions & Sync
    ServerCore -->|"Submit Model (JSON-RPC:8545)"| Bootnode
    FLClientCore -->|"Fetch Model / Submit Proof"| Bootnode
    Bootnode -->|"P2P Sync"| Miner1
    Bootnode -->|"P2P Sync"| Miner2
    Miner1 <-->|"P2P Sync (Ethereum)"| Miner2

    %% Orchestrator Connections
    HTTPServer --> ServerCore
    HTTPClient --> FLClientCore
    SocketServer --> ServerCore
    SocketClient --> FLClientCore

    %% Click Events
    click ServerCore "https://github.com/sylvia969301/blockchain-based-federated-learning/blob/main/BCFL/flwr/server/app.py"
    click FLClientCore "https://github.com/sylvia969301/blockchain-based-federated-learning/blob/main/BCFL/flwr/client/app.py"
    click Strategies "https://github.com/sylvia969301/blockchain-based-federated-learning/tree/main/BCFL/flwr/server/strategy/"
    click GRPCServer "https://github.com/sylvia969301/blockchain-based-federated-learning/blob/main/BCFL/flwr/server/grpc_server/grpc_server.py"
    click GRPCServer "https://github.com/sylvia969301/blockchain-based-federated-learning/blob/main/BCFL/flwr/server/grpc_server/flower_service_servicer.py"
    click GRPCClient "https://github.com/sylvia969301/blockchain-based-federated-learning/blob/main/BCFL/flwr/client/grpc_client/connection.py"
    click GRPCClient "https://github.com/sylvia969301/blockchain-based-federated-learning/blob/main/BCFL/flwr/client/grpc_client/message_handler.py"
    click CIFAR "https://github.com/sylvia969301/blockchain-based-federated-learning/tree/main/BCFL/data/cifar-10-batches-py/"
    click FLServerSim "https://github.com/sylvia969301/blockchain-based-federated-learning/blob/main/BCFL/flwr/simulation/app.py"
    click AggregatedResult "https://github.com/sylvia969301/blockchain-based-federated-learning/tree/main/BCFL/aggregated_result/"
    click CompiledCode "https://github.com/sylvia969301/blockchain-based-federated-learning/blob/main/BCFL/compiled_code.json"
    click Bootnode "https://github.com/sylvia969301/blockchain-based-federated-learning/blob/main/genesis.json"
    click Bootnode "https://github.com/sylvia969301/blockchain-based-federated-learning/blob/main/boot.key"
    click Miner1 "https://github.com/sylvia969301/blockchain-based-federated-learning/tree/main/miner1/"
    click Miner2 "https://github.com/sylvia969301/blockchain-based-federated-learning/tree/main/miner2/"
    click Keystore "https://github.com/sylvia969301/blockchain-based-federated-learning/tree/main/keystore/"
    click Keystore "https://github.com/sylvia969301/blockchain-based-federated-learning/tree/main/BCFL/task_owner_key/"
    click HTTPServer "https://github.com/sylvia969301/blockchain-based-federated-learning/blob/main/BCFL/server_8080.py"
    click HTTPClient "https://github.com/sylvia969301/blockchain-based-federated-learning/blob/main/BCFL/client_8080.py"
    click SocketServer "https://github.com/sylvia969301/blockchain-based-federated-learning/blob/main/BCFL/socket_server.py"
    click SocketClient "https://github.com/sylvia969301/blockchain-based-federated-learning/blob/main/BCFL/socket_client.py"

    %% Styles
    classDef fl fill:#ADD8E6,stroke:#000
    classDef bc fill:#F5CBA7,stroke:#000
    classDef storage fill:#D5F5E3,stroke:#000
    classDef external fill:#DDDDDD,stroke:#000
```
