# cyberdatalab/nebula architecture

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

- Interactive diagram: https://gitdiagram.com/cyberdatalab/nebula
- Repository: https://github.com/cyberdatalab/nebula

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% User
  subgraph "User"
    Browser["User Browser"]:::frontend
  end

  %% Frontend
  subgraph "Frontend Layer"
    UI["Frontend UI (FastAPI, D3.js)"]:::frontend
  end

  %% Controller
  subgraph "Controller Layer"
    ControllerSvc["Controller Service (FastAPI, Docker)"]:::controller
    DB["Controller DB"]:::controller
  end

  %% Core
  subgraph "Core Layer"
    CoreNode["Core Node Engine"]:::core
    subgraph "Core Modules"
      NetMod["Network Module"]:::core
      AggMod["Aggregation Module"]:::core
      TrainMod["Training Module"]:::core
      DataMod["Datasets & Models"]:::core
      SA["Situational Awareness"]:::core
      PB["gRPC & Protobuf Definitions"]:::core
    end
  end

  %% Addons
  subgraph "Plugins & Extensions"
    Addons["Addons (Plugins)"]:::addon
  end

  %% Infrastructure
  subgraph "Infrastructure"
    Infra["Physical & App Scripts"]:::infra
    Docker["Docker"]:::infra
  end

  %% Analysis & Docs
  subgraph "Analysis & Docs"
    Analysis["Analysis Tools"]:::infra
    Docs["Documentation Site"]:::infra
  end

  %% Relationships
  Browser -->|"HTTP REST"| UI
  UI -->|"HTTP REST"| ControllerSvc
  ControllerSvc -->|"RPC (gRPC/Protobuf)"| CoreNode
  CoreNode <-->|"P2P Model Exchange"| CoreNode
  CoreNode -->|"Metrics/Events"| ControllerSvc
  ControllerSvc -->|"WebSocket/REST"| UI
  CoreNode --- Addons
  Infra -->|"Bootstrap"| CoreNode
  CoreNode -->|"Data Export"| Analysis

  %% Click Events
  click UI "https://github.com/cyberdatalab/nebula/tree/main/nebula/frontend/"
  click ControllerSvc "https://github.com/cyberdatalab/nebula/tree/main/nebula/controller/"
  click CoreNode "https://github.com/cyberdatalab/nebula/tree/main/nebula/core/"
  click AggMod "https://github.com/cyberdatalab/nebula/tree/main/nebula/core/aggregation/"
  click NetMod "https://github.com/cyberdatalab/nebula/tree/main/nebula/core/network/"
  click TrainMod "https://github.com/cyberdatalab/nebula/tree/main/nebula/core/training/"
  click DataMod "https://github.com/cyberdatalab/nebula/tree/main/nebula/core/datasets/"
  click DataMod "https://github.com/cyberdatalab/nebula/tree/main/nebula/core/models/"
  click SA "https://github.com/cyberdatalab/nebula/tree/main/nebula/core/situationalawareness/"
  click PB "https://github.com/cyberdatalab/nebula/tree/main/nebula/core/pb/"
  click Addons "https://github.com/cyberdatalab/nebula/tree/main/nebula/addons/"
  click Infra "https://github.com/cyberdatalab/nebula/tree/main/nebula/physical/"
  click Infra "https://github.com/cyberdatalab/nebula/tree/main/app/"
  click Analysis "https://github.com/cyberdatalab/nebula/tree/main/analysis/"
  click Docs "https://github.com/cyberdatalab/nebula/tree/main/docs/"

  %% Styles
  classDef frontend fill:#AEDFF7,stroke:#0366d6,color:#0366d6;
  classDef controller fill:#D6F5D6,stroke:#28a745,color:#28a745;
  classDef core fill:#FFD8A9,stroke:#ff8c00,color:#ff8c00;
  classDef addon fill:#FFE4B5,stroke:#de7e00,color:#de7e00;
  classDef infra fill:#E0E0E0,stroke:#6c757d,color:#6c757d;
```
