# fledge-iot/fledge architecture

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

- Interactive diagram: https://gitdiagram.com/fledge-iot/fledge
- Repository: https://github.com/fledge-iot/fledge

## Overview

##### Main Components
- Core Service: Represent the central management unit (“services/core” and “python/fledge/services/core”) that handles REST APIs, scheduling, configuration management, and orchestrates the other services.
- South Service: Represented by directories “services/south” and “python/fledge/services/south,” these services handle the ingestion of sensor data, interacting with South plugins.
- Storage Service: Found in “services/storage” and “python/fledge/services/storage,” this component buffers sensor data (using SQLite by default, with support for PostgreSQL as well) and stores configuration/metrics.
- Optional/Additional Services: Include visualization, notification, and control dispatcher services (not fully integrated in the core tree but mentioned in the README and sometimes in separate directories or optional modules).

##### Interactions and Integration Points
- Storage Service interacts with plugin components (both for buffering data and executing scheduled purges and backups); indicate data flow from both Core and South services to Storage.
- REST API Endpoint: Show an external REST API (exposed by the Core service) used by local analytical applications and remote management interfaces. This API lets administrators get status updates (status commands as per the README).

##### Architectural Patterns and Principles
- Plugin/Extensibility Model: Clearly represent the plugin pattern where common interfaces allow South, North, and storage plugins to be independently developed and integrated.

##### Relevant Technologies and Frameworks
- Underlying technologies include Linux services, GCC (C/C++), Python, and SQLite (with PostgreSQL support available as an option).
- External integration points such as connections to historians, cloud services, Enterprise systems that Fledge forwards data to.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External nodes
    Sensors["Sensors (IoT Devices)"]:::external
    Historians["Historians/Cloud Services"]:::external

    %% Core Services
    subgraph "Core Service"
        Core_C["Core (C)"]:::core
        Core_P["Core (Python)"]:::core
    end

    %% South Service
    subgraph "South Service"
        South_C["South (C)"]:::service
        South_P["South (Python)"]:::service
    end

    %% Storage Service
    subgraph "Storage Service"
        Storage_C["Storage (C)"]:::service
        Storage_P["Storage (Python)"]:::service
    end

    %% Scheduler Component
    subgraph "Scheduler"
        Scheduler_C["Scheduler (C)"]:::scheduler
        Scheduler_P["Scheduler (Python)"]:::scheduler
    end

    %% REST API Endpoint
    REST_API["REST API Endpoint (Python)"]:::service

    %% Plugin Framework
    subgraph "Plugin Framework"
        subgraph "South Plugins"
            SouthPlugin_C["South Plugin (C)"]:::plugin
            SouthPlugin_P["South Plugin (Python)"]:::plugin
        end
        subgraph "North Plugins"
            NorthPlugin_C["North Plugin (C)"]:::plugin
            NorthPlugin_P["North Plugin (Python)"]:::plugin
        end
        subgraph "Storage Plugins"
            StoragePlugin_C["Storage Plugin (C)"]:::plugin
            StoragePlugin_P["Storage Plugin (Python)"]:::plugin
        end
    end

    %% Optional Services
    subgraph "Optional Services"
        Visualization["Visualization"]:::optional
        Notification["Notification"]:::optional
        ControlDispatcher["Control Dispatcher"]:::optional
    end

    %% Connections and Data Flow
    Sensors -->|"feeds"| South_P
    Core_P -->|"manages"| South_P
    Core_P -->|"manages"| Storage_P
    South_P -->|"sendsData"| Storage_P
    Core_P -->|"schedules"| Scheduler_P
    Scheduler_P -->|"triggers"| South_P
    Scheduler_P -->|"triggers"| Storage_P
    Core_P -->|"exposes"| REST_API
    South_P -->|"interfaces"| SouthPlugin_P
    Storage_P -->|"interfaces"| StoragePlugin_P
    Core_P -->|"integrates"| NorthPlugin_P
    NorthPlugin_P -->|"forwards"| Historians
    Core_P -->|"dispatches"| Visualization
    Core_P -->|"dispatches"| Notification
    Core_P -->|"dispatches"| ControlDispatcher

    %% Click Events for Components
    click Core_C "https://github.com/fledge-iot/fledge/tree/develop/C/services/core"
    click Core_P "https://github.com/fledge-iot/fledge/tree/develop/python/fledge/services/core"
    click South_C "https://github.com/fledge-iot/fledge/tree/develop/C/services/south"
    click South_P "https://github.com/fledge-iot/fledge/tree/develop/python/fledge/services/south"
    click Storage_C "https://github.com/fledge-iot/fledge/tree/develop/C/services/storage"
    click Storage_P "https://github.com/fledge-iot/fledge/tree/develop/python/fledge/services/storage"
    click Scheduler_C "https://github.com/fledge-iot/fledge/tree/develop/C/services/core/scheduler"
    click Scheduler_P "https://github.com/fledge-iot/fledge/tree/develop/python/fledge/services/core/scheduler"
    click REST_API "https://github.com/fledge-iot/fledge/tree/develop/python/fledge/services/core/api"
    click SouthPlugin_C "https://github.com/fledge-iot/fledge/tree/develop/C/plugins/south"
    click SouthPlugin_P "https://github.com/fledge-iot/fledge/tree/develop/python/fledge/plugins/south"
    click NorthPlugin_C "https://github.com/fledge-iot/fledge/tree/develop/C/plugins/north"
    click NorthPlugin_P "https://github.com/fledge-iot/fledge/tree/develop/python/fledge/plugins/north"
    click StoragePlugin_C "https://github.com/fledge-iot/fledge/tree/develop/C/plugins/storage"
    click StoragePlugin_P "https://github.com/fledge-iot/fledge/tree/develop/python/fledge/plugins/storage"

    %% Styling Classes
    classDef core fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef service fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef plugin fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef scheduler fill:#F5CBA7,stroke:#CB4335,stroke-width:2px;
    classDef external fill:#D6DBDF,stroke:#566573,stroke-width:2px;
    classDef optional fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
```
