# fmorsbach/decfl architecture

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

- Interactive diagram: https://gitdiagram.com/fmorsbach/decfl
- Repository: https://github.com/fmorsbach/decfl

## Overview

##### Project type and purpose
- DecFL is a decentralized federated‐learning orchestration framework. It is built in Go with two main binaries (a deploy CLI and a worker service), uses Python/TensorFlow for the actual ML tasks, relies on an Ethereum smart contract for coordination, and can store model artifacts in either Redis (local/dev) or IPFS (distributed).

##### File structure
- Top-level directories:
- app/ → two Go programs:
– app/deploy (deploy.go) – CLI to deploy a model smart contract & push config/scripts to storage
– app/worker (worker.go + Dockerfile) – worker agent that executes training rounds
- model/ → core library with three drivers:
– chain/ (Ethereum interfaces & contract bindings)
– storage/ (Redis and IPFS drivers)
– training/ (TensorFlow driver invoking Python scripts)
- res/ → example model definitions (MNIST, CIFAR10) with configs, weights, and Python scripts
- scenarios/ → per-scenario config for local (ganache+redis) or remote (Infura+IPFS) setups
- multi-node-deployment/ + playbooks/ → Ansible playbooks and YAMLs for multi-host deployment & monitoring
- root scripts (.sh) → build, env setup, deploy_training.sh, start_training.sh, etc.

##### README for architecture insights
- Two scenarios:
1) Local: Docker Compose spins up ganache-cli, Redis, 3 worker containers
2) Multi-node: Ansible provisions hosts, each with Docker, IPFS node, shared Ethereum node (Infura)
- Workflow: setup env → deploy model (deploy_training.sh) → invoke workers (start_training.sh) → track progress via logs or Prometheus/Grafana

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Control Plane"
        DeployCLI["Deploy CLI (Go)"]:::control
        WorkerSvc["Worker Service (Go)"]:::control
    end

    subgraph "Driver Layer"
        ChainInterface["Chain Interface"]:::driver
        EthImpl["Ethereum Driver"]:::driver
        ContractBind["Contract Binding"]:::driver
        CompileScript["Compile Script"]:::driver
        StorageInterface["Storage Interface"]:::driver
        RedisDriver["Redis Driver"]:::driver
        IPFSDriver["IPFS Driver"]:::driver
        TrainOrch["Trainer Orchestrator"]:::driver
        TFTrain["TF Train"]:::driver
        TFAgg["TF Aggregate"]:::driver
        TFEval["TF Evaluate"]:::driver
    end

    subgraph "Data Plane"
        EthereumNode["Ethereum Node"]:::external
        RedisStore["Redis Storage"]:::external
        IPFSCluster["IPFS Cluster"]:::external
        PythonScripts["Python TF Scripts"]:::external
    end

    subgraph "Orchestration & Monitoring"
        LocalComp["Local Docker Compose"]:::orchestr
        MultiNode["Multi-node Deployment"]:::orchestr
        Playbooks["Ansible Playbooks"]:::orchestr
        Monitoring["Prometheus & Grafana"]:::orchestr
        RootScripts["Root Helper Scripts"]:::orchestr
    end

    DeployCLI -->|"RPC"| EthereumNode
    DeployCLI -->|"GET/PUT"| RedisStore
    DeployCLI -->|"GET/PUT"| IPFSCluster

    WorkerSvc -->|"RPC"| EthereumNode
    WorkerSvc -->|"GET/PUT"| RedisStore
    WorkerSvc -->|"GET/PUT"| IPFSCluster
    WorkerSvc -->|"execute scripts"| PythonScripts

    DeployCLI --> ChainInterface
    ChainInterface --> EthImpl
    ChainInterface --> ContractBind
    ChainInterface --> CompileScript

    DeployCLI --> StorageInterface
    StorageInterface --> RedisDriver
    StorageInterface --> IPFSDriver

    WorkerSvc --> TrainOrch
    TrainOrch --> TFTrain
    TrainOrch --> TFAgg
    TrainOrch --> TFEval

    LocalComp -->|provision & start| DeployCLI
    LocalComp -->|provision & start| WorkerSvc

    MultiNode -->|provision & start| DeployCLI
    MultiNode -->|provision & start| WorkerSvc
    Playbooks --> MultiNode

    Monitoring --> WorkerSvc
    Monitoring --> EthereumNode
    Monitoring --> RedisStore
    Monitoring --> IPFSCluster

    classDef control fill:#D0E6FF,stroke:#0275d8,color:#0275d8,stroke-width:1px;
    classDef driver fill:#E6F5D0,stroke:#5CB85C,color:#5CB85C,stroke-width:1px;
    classDef external fill:#F0F0F0,stroke:#636363,color:#636363,stroke-width:1px;
    classDef orchestr fill:#FFE6CC,stroke:#EF7C1C,color:#EF7C1C,stroke-width:1px;

    click DeployCLI "https://github.com/fmorsbach/decfl/blob/master/app/deploy/deploy.go"
    click WorkerSvc "https://github.com/fmorsbach/decfl/blob/master/app/worker/worker.go"
    click EthImpl "https://github.com/fmorsbach/decfl/blob/master/model/chain/ethereum/ethereum.go"
    click ChainInterface "https://github.com/fmorsbach/decfl/blob/master/model/chain/interface.go"
    click ContractBind "https://github.com/fmorsbach/decfl/blob/master/model/chain/ethereum/contract/Model.go"
    click CompileScript "https://github.com/fmorsbach/decfl/blob/master/model/chain/ethereum/contract/compile.sh"
    click StorageInterface "https://github.com/fmorsbach/decfl/blob/master/model/storage/storage.go"
    click RedisDriver "https://github.com/fmorsbach/decfl/blob/master/model/storage/redis.go"
    click IPFSDriver "https://github.com/fmorsbach/decfl/blob/master/model/storage/ipfs.go"
    click TrainOrch "https://github.com/fmorsbach/decfl/blob/master/model/training/trainer.go"
    click TFTrain "https://github.com/fmorsbach/decfl/blob/master/model/training/tensorflow/train.go"
    click TFAgg "https://github.com/fmorsbach/decfl/blob/master/model/training/tensorflow/aggregate.go"
    click TFEval "https://github.com/fmorsbach/decfl/blob/master/model/training/tensorflow/evaluate.go"
    click LocalComp "https://github.com/fmorsbach/decfl/blob/master/scenarios/local/docker-compose.yml"
    click MultiNode "https://github.com/fmorsbach/decfl/blob/master/multi-node-deployment/decfl_deploy.yaml"
    click Playbooks "https://github.com/fmorsbach/decfl/blob/master/playbooks/setup.yml"
    click Monitoring "https://github.com/fmorsbach/decfl/blob/master/multi-node-deployment/monitoring/docker-compose.yaml"
    click RootScripts "https://github.com/fmorsbach/decfl/blob/master/build.sh"
```
