# winc-link/hummingbird architecture

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

- Interactive diagram: https://gitdiagram.com/winc-link/hummingbird
- Repository: https://github.com/winc-link/hummingbird

## Overview

##### Main Components
- HummingBird Core Service: This is the backend implemented in Go (located in cmd/hummingbird-core and under internal/hummingbird). It encapsulates business logic for device management, product management, alert centers, rule engines, and more.
- HummingBird UI: Found in cmd/hummingbird-ui and its build directory, this is the frontend (likely a web SPA) that communicates with the backend.
- Data Storage Layer: The platform supports multiple databases. The use of SQLite and LevelDB is emphasized, with alternatives such as MySQL and TDengine available. The infrastructure directories for MySQL and SQLite (internal/hummingbird/core/infrastructure and manifest/sql) illustrate that storage is pluggable.
- API & Communication Components: There is a rich set of HTTP controllers (gateway, openapi, websocket) and RPC servers (driverserver) that handle client requests, real-time communication, and external integrations.
- Messaging & Device Communication Layer: The presence of MQTT clients, messaging packages, and driver-related modules (internal/pkg/messaging; internal/tools/mqttclient) suggests a messaging subsystem for handling device communication.
- Containers & Dependency Injection: The “container” directories (both under internal/hummingbird and internal/pkg/di) denote that the system uses DI patterns and service containers to manage component interactions.
- Auxiliary Tools: Dockerfiles and Docker Compose files (in the manifest/docker directory) indicate containerized deployment, and utilities like cron jobs (internal/pkg/crontab) and logging, configuration, and error handling play key roles.

##### Relationships & Interactions
- Clients (web browsers, mobile mini-apps, and possibly external systems) interact with the HummingBird UI.
- The UI communicates with the HummingBird Core via HTTP/WS APIs provided by distinct gateway and openapi controllers.
- The Core service orchestrates business logic by invoking various application modules (e.g., deviceapp, driverapp, alertcentreapp) which in turn depend on lower level domain models and interfaces.
- Through the infrastructure and container layers, the business logic interacts with persistent storage via configurations that allow switching between SQLite/LevelDB and MySQL/TDengine.
- The messaging/mqtt layers facilitate bidirectional communication between devices and the platform.
- An RPC server component manages inter-service or driver-specific requests.
- All components are developed in Go, orchestrated and deployed as Docker containers (with deployment details in manifest/docker).

##### Architectural Patterns & Design Principles
- Layered Architecture: Clear separation between controllers (HTTP/RPC), application/business logic, infrastructure (databases, messaging), and domain models.
- Dependency Injection & Inversion of Control: Use of container directories indicates that dependencies are injected to promote loose coupling.
- Pluggability: Database and messaging interfaces are designed to support multiple implementations (e.g., SQLite vs. MySQL, LevelDB vs. TDengine), which is central to the platform’s flexibility.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Clients["External Clients"]:::frontend
        UI["HummingBird UI"]:::frontend
    end

    %% API Gateway / Web Server
    subgraph "API Gateway / Web Server"
        HTTP["HTTP Controllers"]:::backend
        RPC["RPC Server"]:::backend
    end

    %% Business Logic / Application Layer
    subgraph "Business Logic / Application Layer"
        CoreCmd["Core Service (cmd)"]:::backend
        CoreInternal["Core Logic (internal)"]:::backend
    end

    %% Data Storage & Persistence Layer
    subgraph "Data Storage & Persistence Layer"
        SQLITE["SQLite"]:::infrastructure
        LEVELDB["LevelDB"]:::infrastructure
        MYSQL["MySQL"]:::infrastructure
        SQLManifest["SQL Manifest"]:::infrastructure
    end

    %% Messaging & Communication Infrastructure
    subgraph "Messaging & Communication Infrastructure"
        Msg["Messaging Module"]:::infrastructure
        MQTT["MQTT Client"]:::infrastructure
    end

    %% Containers & Dependency Injection
    subgraph "Containers & Dependency Injection"
        DI1["DI Container (Hummingbird)"]:::infrastructure
        DI2["DI Container (pkg)"]:::infrastructure
    end

    %% Auxiliary Tools & Deployment
    subgraph "Auxiliary Tools & Deployment"
        DockerFile["Dockerfile"]:::deployment
        DockerDeploy["Docker Deployment"]:::deployment
        Cron["Cron Jobs"]:::util
        Logger["Logger & Config"]:::util
    end

    %% Connections between layers
    Clients -->|"HTTP/WS"| UI
    UI -->|"HTTP/WS"| HTTP

    HTTP -->|"calls"| CoreCmd
    RPC -->|"RPC"| CoreCmd
    CoreCmd <==>|"sync"| CoreInternal

    %% Data Storage Connections
    CoreCmd -->|"persist"| SQLITE
    CoreCmd -->|"persist"| LEVELDB
    CoreCmd -->|"persist"| MYSQL
    CoreCmd -->|"persist"| SQLManifest

    %% Messaging Connections
    CoreCmd -->|"notify"| Msg
    CoreCmd -->|"communicate"| MQTT

    %% Dependency Injection connections
    CoreCmd -->|"injects"| DI1
    CoreCmd -->|"injects"| DI2

    %% Auxiliary Tools connections
    Cron -->|"schedule"| CoreCmd
    Logger -->|"log/config"| CoreCmd
    DockerFile -->|"builds"| CoreCmd
    DockerDeploy -->|"deploys"| UI
    DockerDeploy -->|"deploys"| CoreCmd

    %% Click Events
    click UI "https://github.com/winc-link/hummingbird/tree/master/cmd/hummingbird-ui"
    click CoreCmd "https://github.com/winc-link/hummingbird/tree/master/cmd/hummingbird-core"
    click CoreInternal "https://github.com/winc-link/hummingbird/tree/master/internal/hummingbird"
    click SQLITE "https://github.com/winc-link/hummingbird/tree/master/internal/hummingbird/core/infrastructure/sqlite"
    click LEVELDB "https://github.com/winc-link/hummingbird/tree/master/internal/tools/datadb/leveldb"
    click MYSQL "https://github.com/winc-link/hummingbird/tree/master/internal/hummingbird/core/infrastructure/mysql"
    click SQLManifest "https://github.com/winc-link/hummingbird/tree/master/manifest/sql"
    click HTTP "https://github.com/winc-link/hummingbird/tree/master/internal/hummingbird/core/controller/http"
    click RPC "https://github.com/winc-link/hummingbird/tree/master/internal/hummingbird/core/controller/rpcserver/driverserver"
    click Msg "https://github.com/winc-link/hummingbird/tree/master/internal/pkg/messaging"
    click MQTT "https://github.com/winc-link/hummingbird/tree/master/internal/tools/mqttclient"
    click DI1 "https://github.com/winc-link/hummingbird/tree/master/internal/hummingbird/core/container"
    click DI2 "https://github.com/winc-link/hummingbird/tree/master/internal/pkg/di"
    click DockerFile "https://github.com/winc-link/hummingbird/tree/master/cmd/hummingbird-core/Dockerfile"
    click DockerDeploy "https://github.com/winc-link/hummingbird/tree/master/manifest/docker"
    click Cron "https://github.com/winc-link/hummingbird/tree/master/internal/pkg/crontab"
    click Logger "https://github.com/winc-link/hummingbird/tree/master/internal/pkg/logger"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef infrastructure fill:#D5F5E3,stroke:#117A65,stroke-width:2px;
    classDef deployment fill:#FADBD8,stroke:#943126,stroke-width:2px;
    classDef util fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
```
