August 9, 2026 5 min read TypeScript fork

FUXA

Abstract

Web-based Process Visualization (SCADA/HMI/Dashboard) software

The Problem

Industrial plants need a low‑cost, web‑based SCADA/HMI that can run on any OS and expose real‑time data from PLCs, MQTT brokers, Modbus devices, etc. Legacy desktop‑only tools force costly licences and OS lock‑in, while custom web stacks are error‑prone and lack a visual editor.

What This Does

FUXA delivers a full‑stack dashboard platform. The backend lives in server/ (Express API, device adapters, Redis/InfluxDB historians) and is started from server/main.js. The frontend is an Angular SPA under client/, compiled to client/dist/. A lightweight Electron wrapper (app/electron/main.js) lets users run the UI locally without a browser. The repository also ships a Node‑RED palette (node-red/node-red-contrib-fuxa) for flow‑based integration.

Key files:

server/api/index.js – defines the REST API, entry functions init and start.
server/runtime/devices/redis/index.js::_buildRedisClient – creates the Redis client used by device adapters.
client/src/app/_services/project.service.ts – central service that loads/saves projects and propagates changes to the UI.
client/src/app/_models/hmi.ts – the hub model imported by 91 other modules (the “hub module”).

How It Is Wired

Execution begins in server/main.js. The function allowCrossDomain (line 368) registers a permissive CORS middleware, then the server imports server/api/index.js.

API boot – init (line 35) wires the Express router, registers device runtimes and reaches 280 internal functions. It is called from 25 places, making it a high‑impact node.
Device runtime – server/runtime/devices/redis/index.js::_buildRedisClient constructs a Redis client (no callers inside the repo, but the client is used by device adapters that read/write tags).
Project handling – client/src/app/_services/project.service.ts is imported by 80 other modules (Ca = 80). It loads JSON project files from the server, updates the model (_models/hmi, _models/device) and triggers UI refreshes. Its large import fan‑out and 1258 LOC make it a change‑impact hotspot.
Hub model – _models/hmi.ts is imported by 91 modules (Ca = 91). It participates in a circular import cycle with gauges.component and gauge‑property.component, increasing cognitive load and risk of runtime errors.
Utility hub – _helpers/utils.ts has Ca = 90, Ce = 0 (no outbound imports). It provides low‑level helpers (e.g., file I/O wrappers) that are widely reused; any modification ripples across the codebase.

The internal call graph shows a few “super‑nodes”: functions named each, attr, $ are called from >100 distinct places, indicating heavy reliance on generic utilities (likely lodash‑style helpers).

External effects:

Filesystem – init → on → e → n reaches a window.open call that writes temporary files.
Network – start → a → o triggers a file‑system open that may be used for downloading device drivers.
Database – device adapters call the Redis client and InfluxDB writer (complete in influxdb/index.js).

Cycles: the import graph contains 18 modules in circular dependencies, the most prominent involving the hub model and gauge components. Breaking these cycles (e.g., extracting shared types into a common module) would lower instability scores and simplify testing.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/FUXA.git
cd FUXA

# Build the Docker image (Dockerfile present)
docker build -t fuxa:local .

# Run the container (exposes UI on 1881)
docker run -d -p 1881:1881 \
  -v fuxa_appdata:/usr/src/app/FUXA/server/_appdata \
  -v fuxa_db:/usr/src/app/FUXA/server/_db \
  -v fuxa_logs:/usr/src/app/FUXA/server/_logs \
  fuxa:local

Alternatively, for local development:

# Backend
cd server
npm ci
npm start   # runs server/main.js

# Frontend
cd ../client
npm ci
npm run build   # produces client/dist/
npm run serve   # serves Angular app

Configuration files are under server/ (e.g., server/_config.json) and client/ (Angular environment files). No secret keys are committed; the README points to environment variables for database credentials.

Real‑World Use

A manufacturing line installs a Raspberry Pi running the Docker image. The Pi connects to a Modbus TCP PLC, stores tag history in InfluxDB, and the UI is accessed from a browser at http://<pi_ip>:1881. Engineers use the web editor to drag SVG gauges onto a dashboard, then export the project JSON for version control.

Code Health & Issues

High – Pin GitHub Actions to commit SHAs (.github/workflows/*).
High – Add a lockfile for node-red/node-red-contrib-fuxa/package.json.
High – Replace wildcard CORS (origin: "*") in server/main.js with an explicit allow list.
High – CI workflows do not run tests; add a test step.
Medium – Declare least‑privilege GITHUB_TOKEN permissions (.github/workflows/docker_image.yml).
Medium – Pin Docker base images by digest (Dockerfile).
Medium – Add a dependency‑vulnerability scan to CI.
Medium – Move large binaries (e.g., client/dist/main.161a5989ea50187f.js 7.7 MiB) to Git LFS.
Medium – Remove generated build output (client/dist/) from VCS.
Medium – Set persist-credentials: false on checkout (.github/workflows/electron_latest.yml).

Additional static findings: 29 deep‑nesting spots, 11 import cycles, 6 oversized files (>1 k LOC), and numerous empty catch {} blocks that silently swallow errors.

The Bottom Line

FUXA provides a functional, Docker‑ready SCADA/HMI stack with a visual editor and broad protocol support, but the codebase suffers from high coupling (hub modules, import cycles) and several security‑hardening gaps. It is suitable for teams that can allocate effort to refactor the core services and tighten CI/CD practices before using it in production.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

1,608 files

TypeScript281
HTML215
JavaScript191
SCSS117
CSS65
JSON46

ReactAngularExpressDocker

Module dependencies

The 10 most depended-upon modules of 444, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_client_src_app__models_hmi["hmi"] n1_lient_src_app__helpers_utils["utils"] n2_pp__services_project_service["project.service"] n3_lient_src_app__models_device["device"] n4_server_runtime_utils["utils"] n5_rty_gauge_property_component["gauge-property.component"] n6_rc_app__services_hmi_service["hmi.service"] n7_ge_base_gauge_base_component["gauge-base.component"] n8_lient_src_app__models_script["script"] n9_client_src_app__models_alarm["alarm"] n9_client_src_app__models_alarm --> n1_lient_src_app__helpers_utils n3_lient_src_app__models_device --> n1_lient_src_app__helpers_utils n3_lient_src_app__models_device --> n8_lient_src_app__models_script n0_client_src_app__models_hmi --> n3_lient_src_app__models_device n6_rc_app__services_hmi_service --> n3_lient_src_app__models_device n6_rc_app__services_hmi_service --> n0_client_src_app__models_hmi n6_rc_app__services_hmi_service --> n9_client_src_app__models_alarm n6_rc_app__services_hmi_service --> n2_pp__services_project_service n6_rc_app__services_hmi_service --> n1_lient_src_app__helpers_utils n2_pp__services_project_service --> n0_client_src_app__models_hmi n2_pp__services_project_service --> n9_client_src_app__models_alarm n2_pp__services_project_service --> n8_lient_src_app__models_script n2_pp__services_project_service --> n3_lient_src_app__models_device n2_pp__services_project_service --> n1_lient_src_app__helpers_utils n7_ge_base_gauge_base_component --> n0_client_src_app__models_hmi n7_ge_base_gauge_base_component --> n1_lient_src_app__helpers_utils n5_rty_gauge_property_component --> n0_client_src_app__models_hmi n5_rty_gauge_property_component --> n8_lient_src_app__models_script classDef cyc stroke:#ef4444,stroke-width:2px; class n0_client_src_app__models_hmi,n5_rty_gauge_property_component cyc;

Dependencies

3 of 3 declared dependencies are a major version behind. Resolved 3 of 3 against the registry.

Package	Declared	Latest	Behind
`electron`	39.8.10	43.4.0	4 major
`sqlite3`	5.1.7	6.0.1	1 major
`electron-builder`	25.1.8	26.15.3	1 major

Open in Code Brain → See its neighbourhood →

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high4

medium7

low1

Pin third-party GitHub Actions to a commit SHAhigh4 occurrences

.github/workflows

docker/setup-qemu-action@v1, docker/setup-buildx-action@v1, docker/login-action@v1, docker/build-push-action@v2

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Commit a lockfile beside the manifesthigh

node-red/node-red-contrib-fuxa/package.json

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Replace the wildcard CORS origin with an explicit allow listhigh

server/main.js

origin: "*"

Any page on the internet can call the API with the browser's cookies attached, so a logged-in visitor to an unrelated site performs authenticated requests without knowing, and the wildcard combined with credentials is the exact configuration browsers refuse for that reason.

Fix: List the origins the API actually serves, and never pair a wildcard with credentials.

Make CI invoke the test suite it hashigh25 occurrences

.github/workflows

25 test files, no test command in the 4 workflows read

A green check that never executed an assertion is worse than no check, because reviewers trust it.

Fix: Add a test step to the existing workflow rather than a new workflow.

Declare least-privilege permissions for GITHUB_TOKENmedium4 occurrences

.github/workflows/docker_image.yml

4 workflow(s) declare no permissions, 3 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Pin the container base image by digestmedium3 occurrences

Dockerfile

node:18-bookworm, node:18-bookworm, node:18-bookworm-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Move large binaries to Git LFS or out of the repositorymedium

client/dist/main.161a5989ea50187f.js

1 blobs over 5MB: main.161a5989ea50187f.js 7.7MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Remove generated build output from version controlmedium345 occurrences

client

345 generated files committed

The reviewer reads src, production runs dist, and a stale bundle means the fix that was reviewed is not the code that executes.

Fix: Gitignore the output directory and build in CI.

Set persist-credentials: false on checkoutmedium

.github/workflows/electron_latest.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/docker_image.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.

View on GitHub All Projects