# unocelli/fuxa architecture

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

- Interactive diagram: https://gitdiagram.com/unocelli/fuxa
- Repository: https://github.com/unocelli/fuxa

## Overview

##### Project Type and Purpose
- FUXA is a full-stack, web-based SCADA/HMI/Dashboard application.
- Frontend: Angular (HTML5/CSS/TypeScript) providing both an editor (design mode) and a runtime viewer (real-time dashboards).
- Backend: Node.js/Express REST API + a real-time runtime engine that manages device connections (Modbus, S7, OPC-UA, BACnet, MQTT, HTTP, etc.), user/project storage, event dispatching, and plugin execution.

##### High-Level File Structure and Architectural Indicators
- Top-level “client” folder: Angular CLI app with src/app, src/assets, environments, build configuration.
- src/app/_services (HTTP/REST, auth, project, plugin, HMI services)
- src/app components organized by feature (alarms, device, editor, gauges, users, etc.)
- Top-level “server” folder: Node.js application
- server/api – Express routes for auth, users, projects, plugins, alarms
- server/runtime – Runtime engine modules: device drivers, alarm storage, DAQ storage, event bus, plugin loader
- server/project*.fuxap & .json – project definition files
- server/jwt-helper.js – JWT auth support
- server/main.js & fuxa.js – bootstrap the HTTP server and runtime engine
- No separate database tier: uses file-based or in-memory JSON stores under server/runtime/storage and server/runtime/project and server/runtime/users.

a. Main Components
- User’s Web Browser (Runs Angular Editor & Viewer)
- Angular Client:
– UI Components (Editor, Dashboard Viewer, Login, Settings)
– Services: AuthService, ProjectService, PluginService, HmiService, ResWebApiService (REST), ResClientService (runtime socket/SSE)
- Node.js Backend:
– API Layer (Express routers under server/api)
– Auth Layer (JWT, auth middleware)
– Runtime Engine (server/runtime):
· Device Connectors (Modbus, S7, OPC-UA, BACnet, MQTT, HTTP-Request, Template)
· Storage Modules (project storage, DAQ storage, user storage)
· Event Dispatcher (push data to clients)
· Plugin Host (load/execute custom plugins)
– File-based storage (project files, default settings)
- External Systems:
– Physical/Virtual Devices (PLC, sensors, actuators) using industrial protocols
- Optional Real-Time Channel: WebSocket or Server-Sent Events between runtime engine and Angular client for live data updates.

b. Relationships & Data Flows
1) Browser → HTTP REST → Node API (login, CRUD on users/projects/plugins)
2) Browser ← HTTP REST ← Node API (serve Angular assets or JSON via CI/CD build)
3) Browser ↔ Real-Time Channel ↔ Runtime Engine (subscribe to data points, alarms, events)
4) Runtime Engine → connects → External Devices via various protocol adapters
5) Runtime Engine → writes/reads → file-based storage (project definitions, DAQ data, user settings)
6) Runtime Engine → triggers → Alarm storage & dispatch

c. Architectural Patterns & Principles
- Layered architecture:
- Presentation (Angular)
- API / Controller (Express routers)
- Domain / Runtime Engine (device abstraction, event bus)
- Persistence (file/in-memory JSON storage)
- Modular design: each device protocol and each feature lives in its own module/folder.
- Separation of concerns: Editor code vs. runtime viewer code; API endpoints vs. runtime engine.
- Plugin architecture: server/runtime/plugins and client/src/app/editor/plugins enable extensibility.

d. Key Technologies & Frameworks
- Frontend: Angular, RxJS, Angular CLI, TypeScript, Webpack (via ng build)
- Backend: Node.js, Express.js, jsonwebtoken (JWT), CommonJS modules
- Device Protocols: modbus-serial, node-opcua, node-bacstack, mqtt.js, S7 drivers, HTTP requests
- Storage: file-based JSON (no external DB), in-memory caches for DAQ and alarm history

##### Essential Elements
- Component names (e.g., AuthService, DeviceConnector, AlarmStorage)
- Data stores (e.g., project.demo.fuxap, prjstorage.js)
- External services/devices and their protocols
- Authentication flow (login → JWT → secured endpoints)
- Plugin loading/execution path
- Runtime event bus pushing to client

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend
    subgraph "Browser" 
        Browser["User's Web Browser"] 
    end

    subgraph "Angular Client" 
        direction TB
        AC["Angular Client"]:::frontend
        subgraph "UI Components"
            direction TB
            Editor["Editor"]:::frontend
            Viewer["Dashboard Viewer"]:::frontend
            Login["Login"]:::frontend
            Settings["Settings"]:::frontend
        end
        subgraph "Services"
            direction TB
            AuthSvc["AuthService"]:::frontend
            PrjSvc["ProjectService"]:::frontend
            PlgSvc["PluginService"]:::frontend
            HmiSvc["HmiService"]:::frontend
            ResWeb["ResWebApiService"]:::frontend
            ResClient["ResClientService"]:::frontend
        end
        Models["Models"]:::frontend
    end

    subgraph "Express API Layer" 
        direction TB
        APIRoot["server/api/index.js"]:::backend
        AuthAPI["Auth Router"]:::backend
        UsersAPI["Users Router"]:::backend
        PrjAPI["Projects Router"]:::backend
        PlgAPI["Plugins Router"]:::backend
        AlarmAPI["Alarms Router"]:::backend
        JWT["JWT Helper"]:::backend
    end

    subgraph "Runtime Engine" 
        direction TB
        RE["Runtime Engine"]:::backend
        Events["Event Dispatcher"]:::backend
        PluginHost["Plugin Host"]:::backend
        Logger["Logger"]:::backend
        Utils["Utilities"]:::backend

        subgraph "Device Connectors"
            direction TB
            Modbus["Modbus Connector"]:::adapter
            S7["S7 Connector"]:::adapter
            OPCUA["OPC-UA Connector"]:::adapter
            BACnet["BACnet Connector"]:::adapter
            MQTT["MQTT Connector"]:::adapter
            HTTPReq["HTTP-Request Connector"]:::adapter
            Template["Template Connector"]:::adapter
            Inmation["Inmation Connector"]:::adapter
        end
    end

    subgraph "Storage" 
        direction TB
        PrjStore["Project Storage"]:::storage
        DAQStore["DAQ Storage"]:::storage
        AlarmStore["Alarm Storage"]:::storage
        UserStore["User Storage"]:::storage
        DefProj["Default Project Files"]:::storage
        Config["Settings & Paths"]:::storage
    end

    subgraph "External Devices" 
        direction TB
        Devices["PLC/Sensors/Actuators"]:::adapter
    end

    %% Connections
    Browser -->|"HTTP REST"| ResWeb
    Browser -->|"HTTP REST"| AC
    Browser -->|"WebSocket/SSE"| ResClient
    AC -->|uses| AuthSvc
    AC -->|uses| PrjSvc
    AC -->|uses| PlgSvc
    AC -->|uses| HmiSvc
    AC -->|calls REST| ResWeb
    AC -->|subscribes| ResClient
    ResWeb -->|HTTP| APIRoot
    APIRoot --> AuthAPI
    APIRoot --> UsersAPI
    APIRoot --> PrjAPI
    APIRoot --> PlgAPI
    APIRoot --> AlarmAPI
    APIRoot --> JWT
    RE --> Events
    RE --> PluginHost
    RE --> Logger
    RE --> Utils
    RE --> PrjStore
    RE --> DAQStore
    RE --> AlarmStore
    RE --> UserStore
    RE --> DefProj
    RE --> Config
    RE --> Modbus
    RE --> S7
    RE --> OPCUA
    RE --> BACnet
    RE --> MQTT
    RE --> HTTPReq
    RE --> Template
    RE --> Inmation
    Modbus -->|"Modbus TCP"| Devices
    S7 -->|"S7"| Devices
    OPCUA -->|"OPC-UA"| Devices
    BACnet -->|"BACnet"| Devices
    MQTT -->|"MQTT"| Devices
    HTTPReq -->|"HTTP"| Devices
    Template -->|"Template"| Devices
    Inmation -->|"Inmation"| Devices

    %% Click Events
    click AC "https://github.com/unocelli/fuxa/tree/master/client/src/app"
    click Editor "https://github.com/unocelli/fuxa/tree/master/client/src/app/editor"
    click Viewer "https://github.com/unocelli/fuxa/tree/master/client/src/app/fuxa-view"
    click Login "https://github.com/unocelli/fuxa/tree/master/client/src/app/login"
    click Settings "https://github.com/unocelli/fuxa/tree/master/client/src/app/app-settings"
    click AuthSvc "https://github.com/unocelli/fuxa/blob/master/client/src/app/_services/auth.service.ts"
    click PrjSvc "https://github.com/unocelli/fuxa/blob/master/client/src/app/_services/project.service.ts"
    click PlgSvc "https://github.com/unocelli/fuxa/blob/master/client/src/app/_services/plugin.service.ts"
    click HmiSvc "https://github.com/unocelli/fuxa/blob/master/client/src/app/_services/hmi.service.ts"
    click ResWeb "https://github.com/unocelli/fuxa/blob/master/client/src/app/_services/rcgi/reswebapi.service.ts"
    click ResClient "https://github.com/unocelli/fuxa/blob/master/client/src/app/_services/rcgi/resclient.service.ts"
    click Models "https://github.com/unocelli/fuxa/tree/master/client/src/app/_models"
    click APIRoot "https://github.com/unocelli/fuxa/blob/master/server/api/index.js"
    click AuthAPI "https://github.com/unocelli/fuxa/blob/master/server/api/auth/index.js"
    click UsersAPI "https://github.com/unocelli/fuxa/blob/master/server/api/users/index.js"
    click PrjAPI "https://github.com/unocelli/fuxa/blob/master/server/api/projects/index.js"
    click PlgAPI "https://github.com/unocelli/fuxa/blob/master/server/api/plugins/index.js"
    click AlarmAPI "https://github.com/unocelli/fuxa/blob/master/server/api/alarms/index.js"
    click JWT "https://github.com/unocelli/fuxa/blob/master/server/api/jwt-helper.js"
    click RE "https://github.com/unocelli/fuxa/blob/master/server/runtime/index.js"
    click Modbus "https://github.com/unocelli/fuxa/blob/master/server/runtime/devices/modbus/index.js"
    click S7 "https://github.com/unocelli/fuxa/blob/master/server/runtime/devices/s7/index.js"
    click OPCUA "https://github.com/unocelli/fuxa/blob/master/server/runtime/devices/opcua/index.js"
    click BACnet "https://github.com/unocelli/fuxa/blob/master/server/runtime/devices/bacnet/index.js"
    click MQTT "https://github.com/unocelli/fuxa/blob/master/server/runtime/devices/mqtt/index.js"
    click HTTPReq "https://github.com/unocelli/fuxa/blob/master/server/runtime/devices/httprequest/index.js"
    click Template "https://github.com/unocelli/fuxa/blob/master/server/runtime/devices/template/index.js"
    click Inmation "https://github.com/unocelli/fuxa/blob/master/server/runtime/devices/inmation/index.js"
    click Events "https://github.com/unocelli/fuxa/blob/master/server/runtime/events.js"
    click PluginHost "https://github.com/unocelli/fuxa/blob/master/server/runtime/plugins/index.js"
    click PrjStore "https://github.com/unocelli/fuxa/blob/master/server/runtime/project/prjstorage.js"
    click DAQStore "https://github.com/unocelli/fuxa/blob/master/server/runtime/storage/daqstorage.js"
    click AlarmStore "https://github.com/unocelli/fuxa/blob/master/server/runtime/alarms/alarmstorage.js"
    click UserStore "https://github.com/unocelli/fuxa/blob/master/server/runtime/users/usrstorage.js"
    click Logger "https://github.com/unocelli/fuxa/blob/master/server/runtime/logger.js"
    click Utils "https://github.com/unocelli/fuxa/blob/master/server/runtime/utils.js"
    click DefProj "https://github.com/unocelli/fuxa/blob/master/server/project.demo.fuxap"
    click Config "https://github.com/unocelli/fuxa/blob/master/server/settings.default.js"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#333,stroke-width:1px
    classDef backend fill:#90ee90,stroke:#333,stroke-width:1px
    classDef adapter fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef storage fill:#d3d3d3,stroke:#333,stroke-width:1px
```
