# waccit/unified-red architecture

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

- Interactive diagram: https://gitdiagram.com/waccit/unified-red
- Repository: https://github.com/waccit/unified-red

## Overview

##### Project type and purpose
- unified-red is a full-stack Node.js application that extends Node-RED with a customizable building-automation HMI (human-machine interface) dashboard.
- It bundles:
- A set of custom Node-RED nodes (in the nodes/ folder) for alarms, data-logging, charts, forms, widgets, etc.
- A backend API (in api/ ) exposing REST controllers, WebSocket endpoints, and database services.
- A modern Angular 9+ frontend (in src/app/ ) that runs at /ui for the live dashboard.
- Static assets (in static/ and src/assets/) for CSS, JS, images, fonts.

##### File-structure highlights and implied architecture
- Top level:
- index.js (entry point) & monitor.js (heartbeat to external monitor server)
- admin-auth.js (Node-RED editor authentication)
- socket.js (WebSocket server attached to Node-RED/Express)
- api/: Express-style controllers (alarm.controller.js, audit.controller.js, etc.), services, models (both mongoose & sequelize variants), db configuration, error handler, email service.
- nodes/: Node-RED node definitions (.html + .js) — these are loaded by Node-RED at runtime.
- src/: Angular application source (components, services, routing).
- static/: served as the httpStatic folder by Node-RED for custom web files.
- Configuration files: api/config.json(default), Angular config (angular.json), Node-RED settings inferred in README.

##### Key README insights
- Backend supports MongoDB or SQL (via mongoose or sequelize).
- Dashboard is served at /ui; Node-RED editor at /admin.
- Authentication with JWT, multi-user, roles, password reset through smtp.
- Real-time updates via WebSocket.
- External integrations: SMTP email, PagerDuty alerts, heartbeat to remote monitor server.

a. Main components
- Client browser — loads Angular SPA (served at /ui)
- Node-RED & Express server — single Node.js process hosting:
– Node-RED runtime & editor (editor at /admin)
– Unified-RED dashboard plugin (Angular SPA + custom Node-RED nodes)
– Express REST API endpoints (/api/…)
– WebSocket server (socket.js)
– Static file server (static/ folder)
- Database(s) — MongoDB or SQL (Postgres/MySQL/etc.)
- External services: SMTP server, PagerDuty API, remote monitor server
- Custom Node-RED nodes (nodes/) interacting via Node-RED message bus

b. Relationships & interactions
1. Browser ↔ HTTP(S): Angular SPA ↔ Express REST API for CRUD (users, alarms, data logs, scheduling).
2. Browser ↔ WebSocket: real-time push for alarm console, charts, notifications.
3. Express services ↔ Database: via mongoose or sequelize ORM layers.
4. Node-RED flows ↔ custom nodes: widget nodes that forward messages to UI via WebSocket.
5. Express email.service ↔ SMTP for password reset.
6. Express PagerDuty integration ↔ PagerDuty API.
7. monitor.js ↔ remote monitor server (heartbeat).

c. Architectural patterns & design principles
- Layered architecture: UI, API, business logic (services), data access (ORM), persistence.
- Plugin/extensibility: custom Node-RED nodes are dropped into the runtime.
- Real-time event streaming via WebSocket.
- Config-driven: config.json and Node-RED settings.js drive behavior (DB, JWT secret, httpStatic).
- MVC-style grouping in API (controllers → services → models).
- SPA frontend organized by feature modules (authentication, dashboard, node-templates, users).

d. Key technologies/frameworks
- Node.js & Express (server)
- Node-RED (runtime & editor)
- Angular 9+ & Bootstrap 4 (SPA)
- Mongoose (MongoDB) & Sequelize (SQL)
- WebSocket (socket.io or native ws via socket.js)
- SMTP (nodemailer) for email
- External APIs (PagerDuty)
- Gulp & npm scripts for build; Angular CLI for SPA build

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend Layer
    subgraph "Frontend (Blue)" 
        direction TB
        Angular["Angular SPA (/ui)"]:::frontend
        EntryHTML["SPA Entry: src/index.html & src/main.ts"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Green)"
        direction TB
        Entry["Entry Point: index.js"]:::backend
        Auth["Auth Middleware: admin-auth.js"]:::backend
        Socket["WebSocket Server: socket.js"]:::backend
        Monitor["Heartbeat: monitor.js"]:::backend

        subgraph "Node-RED Runtime"
            direction TB
            NR["Node-RED Engine"]:::backend
            CustomNodes["Custom Node-RED Nodes (nodes/)"]:::backend
        end

        subgraph "Express API"
            direction TB
            API["Express REST API (api/)"]:::backend
            AlarmC["Alarm Controller"]:::backend
            AlarmS["Alarm Service"]:::backend
            AuditC["Audit Controller"]:::backend
            AuditS["Audit Service"]:::backend
            DatalogC["Data-log Controller"]:::backend
            DatalogS["Data-log Service"]:::backend
            UserC["User & Role Controllers"]:::backend
            UserS["User & Role Services"]:::backend
            InstallC["Install Controller"]:::backend
            InstallS["Install Service"]:::backend
            EmailS["Email Service"]:::backend
            ErrorH["Global Error Handler"]:::backend
            Config["Application Config: api/config.json"]:::backend
            DBConfig["DB Config & ORM (api/db.js, db.mongoose.js, db.sequelize.js)"]:::backend
            Models["Data Models (mongoose & sequelize)"]:::backend
        end

        Static["Static Assets Server (static/ & src/assets/)"]:::backend
    end

    %% Persistence Layer
    subgraph "Persistence (Orange)"
        DB["Database\n(MongoDB | SQL)"]:::persistence
    end

    %% External Systems
    subgraph "External Systems (Gray)"
        SMTP["SMTP Server"]:::external
        PagerDuty["PagerDuty API"]:::external
        MonitorS["Remote Monitor Server"]:::external
    end

    %% Connections
    Angular -->|"HTTP(S) CRUD"| API
    Angular -->|"WebSocket"| Socket
    Entry --> NR
    Entry --> API
    Entry --> Socket
    Entry --> Static
    Entry --> Auth
    Entry --> Monitor
    NR --> CustomNodes
    CustomNodes --> Socket
    API --> DBConfig
    DBConfig --> Models
    Models --> DB
    EmailS --> SMTP
    API -->|"PagerDuty Alerts"| PagerDuty
    Monitor --> MonitorS

    %% Click Events
    click Entry "https://github.com/waccit/unified-red/blob/master/index.js"
    click Monitor "https://github.com/waccit/unified-red/blob/master/monitor.js"
    click Socket "https://github.com/waccit/unified-red/blob/master/socket.js"
    click Auth "https://github.com/waccit/unified-red/blob/master/admin-auth.js"
    click API "https://github.com/waccit/unified-red/tree/master/api/"
    click AlarmC "https://github.com/waccit/unified-red/blob/master/api/alarms/alarm.controller.js"
    click AlarmS "https://github.com/waccit/unified-red/blob/master/api/alarms/alarm.service.js"
    click AuditC "https://github.com/waccit/unified-red/blob/master/api/audit/audit.controller.js"
    click AuditS "https://github.com/waccit/unified-red/blob/master/api/audit/audit.service.js"
    click DatalogC "https://github.com/waccit/unified-red/blob/master/api/datalogs/datalog.controller.js"
    click DatalogS "https://github.com/waccit/unified-red/blob/master/api/datalogs/datalog.service.js"
    click UserC "https://github.com/waccit/unified-red/blob/master/api/users/user.controller.js"
    click UserS "https://github.com/waccit/unified-red/blob/master/api/users/user.service.js"
    click InstallC "https://github.com/waccit/unified-red/blob/master/api/install/install.controller.js"
    click InstallS "https://github.com/waccit/unified-red/blob/master/api/install/install.service.js"
    click DBConfig "https://github.com/waccit/unified-red/blob/master/api/db.js"
    click Models "https://github.com/waccit/unified-red/tree/master/api/models/mongoose/"
    click Config "https://github.com/waccit/unified-red/blob/master/api/config.json"
    click EmailS "https://github.com/waccit/unified-red/blob/master/api/email.service.js"
    click ErrorH "https://github.com/waccit/unified-red/blob/master/api/error-handler.js"
    click CustomNodes "https://github.com/waccit/unified-red/tree/master/nodes/"
    click Static "https://github.com/waccit/unified-red/tree/master/static/"
    click EntryHTML "https://github.com/waccit/unified-red/blob/master/src/index.html"
    click Angular "https://github.com/waccit/unified-red/blob/master/src/app/app.module.ts"
    click Angular "https://github.com/waccit/unified-red/blob/master/src/app/app-routing.module.ts"
    click Angular "https://github.com/waccit/unified-red/blob/master/angular.json"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0288D1,stroke-width:1px;
    classDef backend fill:#D0F8E8,stroke:#00695C,stroke-width:1px;
    classDef persistence fill:#FFE0B2,stroke:#EF6C00,stroke-width:1px;
    classDef external fill:#E0E0E0,stroke:#424242,stroke-width:1px;
```
