# fluidos-project/fluidos-edge architecture

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

- Interactive diagram: https://gitdiagram.com/fluidos-project/fluidos-edge
- Repository: https://github.com/fluidos-project/fluidos-edge

## Overview

##### Project type and purpose
- This is a full-stack IoT Edge system (the “Fluidos Edge” project) that spans from low-level firmware on a sensor board, through edge-side microservices, to Kubernetes-based cloud/edge control planes.
- Purpose: manage and orchestrate edge nodes and devices, collect sensor data (via BLE/MEMS), run mapping/transformation services, and expose/control everything via CloudCore/EdgeCore on Kubernetes.

##### File‐structure analysis
- Top level:
- manifests/ – sample Kubernetes CRDs and Deployment YAMLs for CloudCore/EdgeCore, mapper rollouts, router/policy
- sw/ – submodules for edge system software components:
– FluidosEdge-System (CloudCore, EdgeCore, NodeCore etc.)
– FluidosEdge-Mappers (sensor-to-API translation)
– FluidosEdge-REAR: two Go microservices (connection_manager and edge-resource-manager)
- testbed/ – scripts and YAMLs to spin up a Kind cluster for local testing of CloudCore/EdgeCore and node deployments

##### README insights
- Refers to a multi-layered Edge architecture:
– Physical devices → Edge microservices → CloudCore/EdgeCore (K8s)
– Illustrates Fluidos Edge layers: Device layer, NodeCore/EdgeCore layer, CloudCore layer
- Describes installation of Kubernetes, CloudCore, EdgeCore, and sample deployments

##### Main components
a. Device layer:
b. Edge node software:
- connection_manager (discovers/manages BLE devices)
- edge-resource-manager (manages compute/storage resources on node)
- mappers (FluidosEdge-Mappers) that subscribe to device data and translate to Fluidos data models
- NodeCore (from FluidosEdge-System) that glues together connection_manager, resource-manager, mappers
c. Kubernetes control plane:
- EdgeCore (runs on edge clusters, orchestrates NodeCore, sidecar pods)
- CloudCore (runs on cloud cluster, central control, stores state)
d. External systems:
- etcd/DB (CloudCore state store)
- CLI/UI (kubectl or Fluidos UI)

##### Relationships and data flows
- Firmware → (BLE) → connection_manager
- connection_manager → publishes events to mappers or NodeCore event bus
- mappers → transform sensor data → NodeCore API
- NodeCore → EdgeCore CRDs (via Kubernetes API)
- EdgeCore ↔ CloudCore sync (object sync CRDs)
- CloudCore → stores global state, provides UI/REST API

##### Architectural patterns/design principles
- Microservices on edge nodes (connection_manager, resource-manager, mappers)
- Kubernetes CRD-based control plane (CloudCore/EdgeCore)
- Event-driven data flow (BLE events → message bus → mapper → API)
- Separation of concerns: firmware vs. edge services vs. orchestrator vs. cloud

##### Technologies, frameworks, libraries
- Firmware: STM32Cube HAL, CMSIS, BlueNRG BLE stack, X-Cube-MEMS middleware
- Edge services: Go modules (go.mod), standard library, custom Fluidos utilities
- Orchestration: Kubernetes, CRDs (apps_v1alpha1_edgeapplication, nodegroup, device models, router rules, etc.)
- Testing: Kind cluster, Helm charts, sample YAMLs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Device Layer
    subgraph "Device Layer"
        direction TB
        Firmware["Firmware (STM32U5 BLE+Sensors)"]:::device
    end

    %% Edge Node Layer
    subgraph "Edge Node Layer"
        direction TB
        CM["connection_manager"]:::edge
        ERM["edge-resource-manager"]:::edge
        MessageBus["Event Bus"]:::edge
        Mappers["FluidosEdge-Mappers"]:::edge
        NodeCore["NodeCore Runtime"]:::edge
    end

    %% EdgeCore Layer
    subgraph "EdgeCore Control Plane"
        direction TB
        K8sAPI["Kubernetes API"]:::control
        EdgeCore["EdgeCore Controller"]:::control
        Manifests["CRD & Deployment Manifests"]:::control
    end

    %% CloudCore Layer
    subgraph "CloudCore Control Plane"
        direction TB
        CloudCore["CloudCore Controller"]:::cloud
        DB["etcd/Database"]:::cloud
        UI["CLI/UI"]:::external
    end

    %% Testbed Environment
    subgraph "Testbed Environment"
        direction TB
        Testbed["Kind Cluster & Scripts"]:::testbed
    end

    %% Relationships
    Firmware -->|"BLE"| CM
    CM -->|Publishes Events| MessageBus
    MessageBus -->|Subscribes| Mappers
    Mappers -->|"Transforms Data"| NodeCore
    NodeCore -->|"K8s API Calls"| K8sAPI
    K8sAPI -->|Manages CRDs| EdgeCore
    EdgeCore <-->|"Sync CRDs"| CloudCore
    CloudCore -->|"Stores State"| DB
    CloudCore -->|"Exposes API"| UI
    Testbed -->|"Emulates Edge & Cloud"| EdgeCore

    %% Click Events
    click Firmware "https://github.com/fluidos-project/fluidos-edge/tree/main/fw/FluidosEdge_STWINBX1_MEMS_BLE2_Sources/FluidosEdge_STWINBX1_MEMS_BLE2"
    click CM "https://github.com/fluidos-project/fluidos-edge/blob/main/sw/FluidosEdge-REAR/connection_manager/main.go"
    click CM "https://github.com/fluidos-project/fluidos-edge/tree/main/sw/FluidosEdge-REAR/connection_manager/utils_fe/"
    click ERM "https://github.com/fluidos-project/fluidos-edge/blob/main/sw/FluidosEdge-REAR/edge-resource-manager/main.go"
    click Mappers "https://github.com/fluidos-project/fluidos-edge/tree/main/sw/FluidosEdge-Mappers/BLE/"
    click Mappers "https://github.com/fluidos-project/fluidos-edge/tree/main/sw/FluidosEdge-Mappers/BLE/ble"
    click Mappers "https://github.com/fluidos-project/fluidos-edge/blob/main/sw/FluidosEdge-Mappers/BLE/config.yaml"
    click Mappers "https://github.com/fluidos-project/fluidos-edge/blob/main/sw/FluidosEdge-Mappers/BLE/deviceProfile.json"
    click NodeCore "https://github.com/fluidos-project/fluidos-edge/tree/main/sw/FluidosEdge-System/"
    click Manifests "https://github.com/fluidos-project/fluidos-edge/tree/main/manifests/"
    click Manifests "https://github.com/fluidos-project/fluidos-edge/tree/main/manifests/samples/devices/"
    click Manifests "https://github.com/fluidos-project/fluidos-edge/blob/main/manifests/samples/mapper/BTmapper-Deployment.yaml"
    click Testbed "https://github.com/fluidos-project/fluidos-edge/tree/main/testbed/kind/"
    click Testbed "https://github.com/fluidos-project/fluidos-edge/tree/main/testbed/kind/deployments/edge/cloudcore/crds/"
    click Testbed "https://github.com/fluidos-project/fluidos-edge/tree/main/testbed/kind/deployments/node/crds/"
    click Testbed "https://github.com/fluidos-project/fluidos-edge/tree/main/testbed/kind/deployments/node/samples/"
    click Testbed "https://github.com/fluidos-project/fluidos-edge/blob/main/testbed/kind/setup.sh"
    click Testbed "https://github.com/fluidos-project/fluidos-edge/tree/main/testbed/kind/provider/"

    %% Styles
    classDef device fill:#e0ffe0,stroke:#333,stroke-width:1px
    classDef edge fill:#e0f0ff,stroke:#333,stroke-width:1px
    classDef control fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef cloud fill:#E1BEE7,stroke:#333,stroke-width:1px
    classDef testbed fill:#F5F5F5,stroke:#666,stroke-dasharray: 2 2
    classDef external fill:#ddd,stroke:#333,stroke-width:1px,stroke-dasharray:2 2
```
