How cyberdatalab/nebula works
Project type and purpose
• NEBULA is a full-stack, modular platform for decentralized federated learning.
• Three core subsystems:
– Frontend (web UI)
– Controller (orchestrator)
– Core (node-level federated engine)
• Supporting modules: physical device provisioning, data/network analysis, plugins (“addons”), documentation.
Top-level components
A. Frontend
– Code: nebula/frontend
– Tech: FastAPI, HTML/CSS/JS, D3.js network visualizations
– Responsibilities: user authentication, scenario setup, real-time monitoring
B. Controller
– Code: nebula/controller
– Tech: FastAPI REST endpoints, Docker, embedded database (controller/database.py)
– Responsibilities: dispatch scenarios, manage device metadata, store metrics, start/stop services
C. Core (Node Engine)
– Code: nebula/core
– Sub-modules:
• network (peer discovery, messaging, health checks)
• aggregation (FedAvg, Krum, TrimmedMean, etc.)
• training (PyTorch Lightning loops, scikit, Siamese)
• datasets & models (built-in CIFAR, EMNIST, MNIST, sentiment)
• situational awareness & trustworthiness
• utils (logging, certificates, tasks)
– Responsibilities: on-device training, update propagation, plugin execution
D. Addons (Plugins)
– Code: nebula/addons
– Categories: attacks, GPS, mobility, reputation, WAF, trustworthiness reports
– Responsibilities: extend core with extra behaviors (adversarial attacks, network sim, security)
E. Physical & App Layer
– Code: nebula/physical & app/
– Responsibilities: OS‐specific install/run scripts, certificate management, device provisioning
F. Analysis & Docs
– analysis/: data & network post-hoc analysis tools
– docs/: MkDocs site, prebuilt markdown, static assets
Relationships & data flows
1. User (browser) → Frontend UI
2. Frontend → Controller via REST (FastAPI)
3. Controller → Nodes (Core) via RPC/messaging (gRPC, protobuf)
4. Core nodes ↔ Core nodes (peer-to-peer model update exchange)
5. Core nodes → Controller (metrics, logs)
6. Controller → Frontend (live metrics, topology)
Important architectural patterns
• Microservices / layered services: separate UI, orchestration, compute
• Plugin architecture: addons loaded via core/addonmanager
• Event-driven network: message bus for model updates, health checks
• MVC on frontend, modular Python packages everywhere
Technologies & frameworks
• FastAPI (REST API for frontend & controller)
• D3.js (network visualization)
• PyTorch Lightning & Tensorboard (training & monitoring)
• Docker (controller & frontend containers)
• protobuf/gRPC (nebula/core/pb)