# busy-cloud/iot architecture

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

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

## Overview

##### Main Components
- Entry Point/Application Bootstrap: The cmd directory (cmd/main.go) serves as the launching point of the application. Additionally, files like app/boot.go and internal/boot.go indicate the initialization routines.
- Business Modules / Domain Logic:
– Product Module: Contains the product model logic (files like product/config.go, product/model.go, product/product.go, and product_api.go). This module handles the "thing model" as specified in the README.
– Device Module: Found in the device directory and further supported by internal/device.go and device_api.go. It likely concerns interfacing with and managing IoT devices.
– Project Module: Manages projects using files such as project/project.go and project-related API files.
– Space Module: Handles grouping or configuration of “spaces” with files like space/space.go and space-api.go.
– Alarm Module: Located in the alarm directory, handling alarms via alarm.go and alarm_api.go.
– Protocol Module and Protocols: The protocol directory (protocol.go, store.go) and the protocols directory (modbus.json, etc.) deal with protocol definitions and implementations. This might include communication standards like Modbus.
- Utility and Calculation Modules:
– Bin and Calc: The bin and calc directories hold utility functions (e.g., checksum, hex conversion, a language processor in calc/lang.go) that support other modules.
- Internal Services:
– The internal directory contains shared services such as MQTT handling (internal/mqtt.go) and validation logic (internal/validator.go), providing infrastructural support.
- UI/Templates:
– Menus and Pages: The menus (with JSON files) and pages directories (pages/iot with numerous JSON configuration files) represent UI configuration, likely used by a frontend or a web manager for the IoT system.

##### Relationships and Interactions
- The Entry Point (cmd/main.go) initializes the application, then routes requests/commands to various business modules.
- API Layers: Many modules have corresponding API implementations (e.g., alarm_api.go, device_api.go, project-api.go, product_api.go) that expose functionality to clients or other services.
- Communication: Modules like internal/mqtt.go suggest asynchronous or message-based communication, especially for device telemetry or control.
- Dependency and Utility Layers: The utility functions in bin/ and calc/ serve supporting roles for various components. Likewise, boot routines (both in app and internal) indicate setup dependencies.
- Configurations for UI: The JSON files in pages/iot/ and menus provide configurations for the user interfaces, linking the backend logic with the frontend presentation.

##### Architectural Patterns and Principles
- Modular Design: Each domain (product, device, project, space, alarm, protocol) is encapsulated into its own directory with both core logic and API endpoints.
- Separation of Concerns: API files are distinct from core business logic, and there is a clear division between frontend-related configuration (menus/pages) and backend services.
- Reusable Internal Services: The internal folder provides foundational support (bootstrapping, MQTT, validation) that underpins multiple components.
- Integrated Utility Components: The bin and calc modules are dedicated to common operations like data conversion or language processing.
- Monolithic Architecture: Although the project is broken down into subcomponents, it is all bundled together rather than split into independent microservices.

##### Final Summary
– Entry Point: cmd/main.go, boot routines (app/boot.go, internal/boot.go)
– Business Modules: Product, Device, Project, Space, Alarm, Protocol(s)
– Internal/Infrastructural Services: MQTT, Validator, Utility Modules (bin, calc)
– Presentation/UI: JSON configuration in menus and pages
– Integration: Interactions among modules via APIs and internal calls

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        UIMenus["UI: Menus"]:::presentation
        UIPages["UI: Pages"]:::presentation
    end

    %% Entry and Bootstrap Layer
    subgraph "Entry and Bootstrap"
        Entry["Command Entry (cmd/main.go)"]:::entry
        AppBoot["App Boot (app/boot.go)"]:::entry
        IntBoot["Internal Boot (internal/boot.go)"]:::entry
    end

    Entry --> AppBoot
    Entry --> IntBoot

    %% Application Layer (Business Modules and APIs)
    subgraph "Application Layer"
        %% Product Module
        ProdAPI["Product API (product/product_api.go)"]:::api
        ProdBusiness["Product Module (product)"]:::module
        ProdAPI -->|"calls"| ProdBusiness

        %% Device Module
        DevAPI["Device API (device/device_api.go)"]:::api
        DevBusiness["Device Module (device)"]:::module
        DevAPI -->|"calls"| DevBusiness

        %% Project Module
        ProjAPI["Project API (project/project-api.go)"]:::api
        ProjBusiness["Project Module (project)"]:::module
        ProjAPI -->|"calls"| ProjBusiness

        %% Space Module
        SpaceAPI["Space API (space/space-api.go)"]:::api
        SpaceBusiness["Space Module (space)"]:::module
        SpaceAPI -->|"calls"| SpaceBusiness

        %% Alarm Module
        AlarmAPI["Alarm API (alarm/alarm_api.go)"]:::api
        AlarmBusiness["Alarm Module (alarm)"]:::module
        AlarmAPI -->|"calls"| AlarmBusiness

        %% Protocol Module
        ProtoAPI["Protocol API (protocol/api.go)"]:::api
        ProtoBusiness["Protocol Module (protocol)"]:::module
        ProtoAPI -->|"calls"| ProtoBusiness
        %% Protocol Definitions
        ProtoDefs["Protocol Definitions (protocols)"]:::api
        ProtoBusiness -->|"defines"| ProtoDefs
    end

    %% Routing from Entry Point to Application Layer APIs
    Entry -->|"routes"| ProdAPI
    Entry -->|"routes"| DevAPI
    Entry -->|"routes"| ProjAPI
    Entry -->|"routes"| SpaceAPI
    Entry -->|"routes"| AlarmAPI
    Entry -->|"routes"| ProtoAPI

    %% Infrastructure / Internal Services
    subgraph "Internal Services"
        MQTT["MQTT Service (internal/mqtt.go)"]:::infra
        Validator["Validator (internal/validator.go)"]:::infra
    end

    DevAPI -->|"uses"| MQTT
    ProjAPI -->|"validates"| Validator
    SpaceAPI -->|"validates"| Validator

    %% Utility Modules
    subgraph "Utility Modules"
        BinUtil["Bin Utilities (bin)"]:::utility
        CalcUtil["Calc Utilities (calc)"]:::utility
    end

    ProdBusiness -->|"utilizes"| BinUtil
    ProdBusiness -->|"utilizes"| CalcUtil
    DevBusiness -->|"utilizes"| BinUtil
    DevBusiness -->|"utilizes"| CalcUtil
    AlarmBusiness -->|"utilizes"| BinUtil
    ProtoBusiness -->|"utilizes"| BinUtil

    %% Interaction with Presentation/UI Components
    ProjBusiness -->|"updates"| UIPages
    ProjBusiness -->|"updates"| UIMenus

    %% Click Events
    click Entry "https://github.com/busy-cloud/iot/blob/main/cmd/main.go"
    click AppBoot "https://github.com/busy-cloud/iot/blob/main/app/boot.go"
    click IntBoot "https://github.com/busy-cloud/iot/blob/main/internal/boot.go"

    click ProdAPI "https://github.com/busy-cloud/iot/blob/main/product/product_api.go"
    click ProdBusiness "https://github.com/busy-cloud/iot/tree/main/product/"

    click DevAPI "https://github.com/busy-cloud/iot/blob/main/device/device_api.go"
    click DevBusiness "https://github.com/busy-cloud/iot/blob/main/device/device.go"

    click ProjAPI "https://github.com/busy-cloud/iot/blob/main/project/project-api.go"
    click ProjBusiness "https://github.com/busy-cloud/iot/blob/main/project/project.go"

    click SpaceAPI "https://github.com/busy-cloud/iot/blob/main/space/space-api.go"
    click SpaceBusiness "https://github.com/busy-cloud/iot/blob/main/space/space.go"

    click AlarmAPI "https://github.com/busy-cloud/iot/blob/main/alarm/alarm_api.go"
    click AlarmBusiness "https://github.com/busy-cloud/iot/blob/main/alarm/alarm.go"

    click ProtoAPI "https://github.com/busy-cloud/iot/blob/main/protocol/api.go"
    click ProtoBusiness "https://github.com/busy-cloud/iot/blob/main/protocol/protocol.go"
    click ProtoDefs "https://github.com/busy-cloud/iot/blob/main/protocols/modbus.json"

    click BinUtil "https://github.com/busy-cloud/iot/tree/main/bin/"
    click CalcUtil "https://github.com/busy-cloud/iot/blob/main/calc/lang.go"

    click MQTT "https://github.com/busy-cloud/iot/blob/main/internal/mqtt.go"
    click Validator "https://github.com/busy-cloud/iot/blob/main/internal/validator.go"

    click UIMenus "https://github.com/busy-cloud/iot/blob/main/menus/iot.json"
    click UIPages "https://github.com/busy-cloud/iot/tree/main/pages/iot/"

    %% Styles
    classDef presentation fill:#a2d9ff,stroke:#333,stroke-width:2px;
    classDef entry fill:#a9dfbf,stroke:#333,stroke-width:2px;
    classDef api fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef module fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef infra fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef utility fill:#d7bde2,stroke:#333,stroke-width:2px;
```
