eDEX-UI Administrator & Developer Guide

This guide is the complete technical reference for eDEX-UI: its architecture, the terminal client/server design, the system-monitoring pipeline, security model, configuration surface, build and distribution process, and per-module internals. It is written for administrators deploying eDEX-UI (including kiosk/touchscreen scenarios), developers building from source or authoring themes and keyboard layouts, and architects who want to understand how the project works end to end.

It is the companion to the User Guide, which covers day-to-day usage. Everything here is derived directly from the eDEX-UI source at commit 04a00c4 (version 2.2.8).

1. Executive Summary

eDEX-UI is an Electron desktop application that presents a fullscreen, TRON-inspired "computer console" UI wrapping a real terminal emulator and a suite of live system monitors. It is cross-platform (Windows, macOS, Linux), single-window, single-instance, and fullscreen by default.

Architectural shape

eDEX-UI is a two-process Electron app with an unusual internal twist: the terminal is wired together with a localhost WebSocket between the renderer (xterm.js front-end) and the main process (node-pty back-end), rather than going purely through Electron IPC. The main process additionally spins up a cluster of Node worker processes to offload systeminformation polling so the UI stays smooth.

        ┌──────────────────────── Electron main process (Node.js) ───────────────────────┐
        │  src/_boot.js                                                                   │
        │   • single-instance lock, settings/shortcuts/theme bootstrapping               │
        │   • creates the BrowserWindow (loads src/ui.html)                               │
        │   • Terminal (role:"server") → node-pty + ws WebSocket server (:3000, :3002-5)  │
        │   • src/_multithread.js → cluster of N workers running systeminformation        │
        │   • IPC handlers: ttyspawn, theme/kb override, systeminformation-call, log      │
        └───────────────▲───────────────────────────────▲───────────────────────────────┘
                        │ Electron IPC                   │ WebSocket  ws://127.0.0.1:<port>
                        │ (resize, cwd, process, si)     │ (keystrokes ↔ pty output)
        ┌───────────────┴───────────────────────────────┴───────────────────────────────┐
        │  Electron renderer process (Chromium) — src/ui.html + src/_renderer.js         │
        │   • boot animation → initUI() builds the layout                                 │
        │   • 18 module classes in src/classes/ (Terminal client, Keyboard, FS, monitors) │
        │   • window.si Proxy → IPC → main-process worker cluster                         │
        └────────────────────────────────────────────────────────────────────────────────┘

Note

Because the project is archived, this guide also calls out which subsystems are known to be fragile (GeoIP lookup, proxy handling, Windows CWD tracking) so operators know what to expect rather than discovering it in production.

2. System Architecture

2.1 Process model

2.2 Startup sequence

The boot flow in src/_boot.js (app.on('ready', …)) proceeds:

1. Single-instance lock via app.requestSingleInstanceLock(). A second launch logs "Another instance of eDEX is already running" and exits.
2. GPU tuning — appends Chromium switches ignore-gpu-blocklist, enable-gpu-rasterization, enable-video-decode to trade some stability for rendering performance (notably on Linux).
3. Proxy env scrubbing — http_proxy / https_proxy are deleted from the environment to avoid breaking the internal WebSocket connections (issue #222).
4. Config bootstrapping — creates the user-data directory and writes default settings.json, shortcuts.json, and lastWindowState.json if absent; mirrors the built-in themes/, keyboards/, and fonts/ into the user-data directory (overwriting each launch).
5. Version history — appends the current version + timestamp to versions_log.json.
6. Shell resolution — resolves the configured shell to an absolute path with which. Failure here stalls startup at "Settings loaded!".
7. Environment assembly — loads a clean login shell environment via shell-env, then overlays TERM=xterm-256color, COLORTERM=truecolor, TERM_PROGRAM=eDEX-UI, TERM_PROGRAM_VERSION, plus any user env.
8. Terminal back-end — instantiates Terminal({role:"server", …}) on settings.port (default 3000).
9. Multithread controller — require("./_multithread.js") forks the worker cluster.
10. Window creation — createWindow(settings) builds the BrowserWindow and loads ui.html.
11. Extra-tab back-ends — reserves four extra TTY slots on ports basePort+2 … basePort+5 for additional tabs.

2.3 The terminal: a WebSocket-bridged client/server

The single most important design element lives in src/classes/terminal.class.js, which is one class with two roles:

Server role (main process)

node-pty spawn(shell, args, {cols, rows, cwd, env})
        │
        ├── ws WebSocket server on settings.port (verifyClient: max 1 client)
        │      ws "message"  → tty.write(msg)        (keystrokes in)
        │      tty.onData     → ws.send(data)         (pty output out)
        │
        └── 1-second tick:  CWD tracking + foreground-process tracking
               Linux : readlink /proc/<pid>/cwd ;  ps -o comm ... -g <pid>
               macOS : lsof -a -d cwd -p <pid>  ;  ps -o comm ... -g <pid>
               Windows: unsupported → "Fallback cwd" (detached mode)

• node-pty spawns the actual shell. Non-Windows shells get --login by default when no shellArgs are set.
• A ws WebSocket server is created on the port. verifyClient rejects a second connection, so each pty has exactly one front-end.
• Keystrokes arrive as WebSocket messages and are written to the pty; pty output is sent back over the socket.
• Every second the server updates the current working directory and the foreground process name and pushes them to the renderer over the Electron IPC channel terminal_channel-<port>.

Client role (renderer)

• Builds an xterm.js Terminal with the FitAddon, WebglAddon, LigaturesAddon, and AttachAddon.
• Opens new WebSocket("ws://127.0.0.1:<port>"); the AttachAddon binds the socket to xterm so output renders and input is sent.
• Resize is negotiated over IPC (terminal_channel-<port> → "Resize"), recomputed by FitAddon.proposeDimensions() with aspect-ratio correction heuristics.
• Receives "New cwd", "Fallback cwd", and "New process" IPC messages — the CWD drives the filesystem panel; the process name drives the tab label.

Important

The WebSocket server binds to the loopback interface and accepts only one client per port, but it performs no authentication. Any local process able to reach 127.0.0.1:<port> before the renderer connects could occupy the socket. On a single-user desktop this is low-risk; on shared/multi-user hosts treat the terminal ports as a local trust boundary. See Security.

2.4 Multi-tab terminals

initUI() creates the main terminal on settings.port. Up to four additional tabs are supported (five total). When a user opens an empty tab, the renderer sends an ttyspawn IPC; the main process allocates the next free port from the reserved pool (basePort+2 … basePort+5), spawns a new Terminal server in the active tab's current working directory, and replies with ttyspawn-reply: SUCCESS: <port>. If the pool is exhausted it replies ERROR: max number of ttys reached.

2.5 The systeminformation pipeline (window.si)

System data is the heaviest workload, so it is offloaded from the renderer:

renderer:  window.si.cpu()        (a Proxy)
   │  ipc.send("systeminformation-call", "cpu", id, ...args)
   ▼
main (_multithread.js master):
   • dispatch round-robin to a worker  (or call inline if args.length>1)
   ▼
worker:  si["cpu"](...).then(res => process.send({id, res}))
   ▲
   │  ipc "systeminformation-reply-<id>"
renderer: Promise resolves with res

• window.si in the renderer is a JavaScript Proxy. Any property access (window.si.cpu, window.si.mem, …) returns a function that round-trips through IPC and resolves a Promise.
• The master (_multithread.js) forks min(os.cpus().length - 1, 7) workers (leaving a core for the renderer; capped at 7 per issue #904).
• Calls are dispatched round-robin to workers; multi-argument calls are executed inline by the master.
• An illegal method name (si[type] undefined) is rejected with a warning, preventing arbitrary function invocation through the channel.

2.6 Rendering and UI construction

src/_renderer.js orchestrates the front-end:

1. Disables eval() globally (window.eval / global.eval throw) as a hardening measure.
2. Defines HTML/CSS sanitization helpers (_escapeHtml, _purifyCSS, _encodePathURI).
3. Loads settings.json, shortcuts.json, lastWindowState.json and applies CLI overrides (--nointro, --nocursor).
4. Loads the theme (_loadTheme) — injects CSS variables, fonts, and any theme-defined injectCSS (purified).
5. Runs the boot animation (unless nointro) reading assets/misc/boot_log.txt.
6. initUI() builds the DOM scaffold and instantiates every module in order (see Module Reference).
7. Registers global keyboard shortcuts via electron.remote.globalShortcut, re-registering on window focus and clearing on blur.

3. Repository Structure

edex-ui/
├── package.json              Root: build config (electron-builder), dev deps, scripts
├── src/
│   ├── _boot.js              Main process entry (package.json "main")
│   ├── _renderer.js          Renderer orchestration
│   ├── _multithread.js       systeminformation worker cluster
│   ├── ui.html               Renderer HTML shell
│   ├── package.json          Runtime deps (xterm, node-pty, ws, systeminformation, …)
│   ├── classes/              18 ES6 module classes (see §7)
│   └── assets/
│       ├── css/              Per-module stylesheets (mod_*.css, main.css, boot_screen.css)
│       ├── themes/           20 built-in theme JSON files
│       ├── kb_layouts/       19 keyboard layout JSON files
│       ├── fonts/            Fira Code/Mono, United Sans (woff2)
│       ├── audio/            13 sound-effect WAV files
│       ├── icons/            file-icons.json (generated SVG icon set)
│       ├── misc/             boot_log.txt, file-icons-match.js, grid.json
│       └── vendor/           encom-globe.js (3-D globe library)
├── file-icons/               Git submodules: icon source sets (atom, devopicons, etc.)
├── file-icons-generator.js   Regenerates file-icons.json + matcher from submodules
├── prebuild-minify.js        CI minification of src before packaging
├── media/                    App icons + screenshots
├── SECURITY.md
└── LICENSE                   GPL-3.0

Key file roles

4. Requirements

4.1 Runtime (release binaries)

4.2 Build-from-source

4.3 Runtime dependencies (src/package.json)

5. Security Model

eDEX-UI follows the permissive Electron security posture that was common before the contextBridge hardening era, because the renderer needs broad Node.js access to run terminals, read the filesystem, and call native modules. This is a deliberate design trade-off, not an oversight — but administrators deploying it (especially on shared or kiosk machines) should understand it precisely.

5.1 BrowserWindow webPreferences (from src/_boot.js)

Warning

With nodeIntegration:true and contextIsolation:false, any code that executes in the renderer has full local user privileges (filesystem, process spawning, network). eDEX mitigates this by only ever loading its own local file:// UI and locking navigation — but if you extend eDEX or inject untrusted CSS/HTML/themes, you are running it inside a fully privileged context.

5.2 Mitigations actually present in the code

eDEX does not rely on a sandbox; instead it constrains what can run:

5.3 Network egress

eDEX makes several outbound connections. There are no inbound listeners except the loopback terminal WebSockets.

Caution

On restricted / proxied networks these lookups fail. eDEX scrubs http_proxy/https_proxy at startup and does not offer proxy configuration (issue #1050), so the network panels may stay blank behind a corporate proxy. This does not affect the terminal itself.

5.4 Things that do not exist (negative knowledge)

To prevent fabricated configuration assumptions:

• No HTTP/REST API. eDEX exposes nothing over HTTP; the only sockets are the loopback terminal WebSockets.
• No authentication or multi-user model. It is a single-user desktop app.
• No remote management, telemetry, or analytics. The only outbound calls are those listed in §5.3.
• No plugin system or extension API. Customization is limited to themes, keyboard layouts, settings, and shortcuts.
• No environment-variable configuration. All configuration is via JSON files in the user-data directory (and two CLI flags).
• No system-wide config file. Configuration is strictly per-user under the Electron userData path.

5.5 Known security-relevant issues

6. Configuration Reference

All configuration lives in the Electron user-data directory:

6.1 settings.json — complete reference

Defaults are those written by _boot.js on first run. Keys marked (editor) are exposed in the settings editor but have no hardcoded default.

Note

experimentalGlobeFeatures makes the terminal client scan all pty output for IPv4 addresses and pin them on the globe (issue #397). This means terminal content is parsed by a regex on every message — disable it if you process sensitive output or want lower CPU usage.

6.2 shortcuts.json — schema

An array of shortcut objects:

[
  { "type": "app",   "trigger": "Ctrl+Shift+C", "action": "COPY",     "enabled": true },
  { "type": "app",   "trigger": "Ctrl+X",       "action": "TAB_X",    "enabled": true },
  { "type": "shell", "trigger": "Ctrl+Shift+Alt+Space", "action": "neofetch", "linebreak": true, "enabled": false }
]

App action identifiers: COPY, PASTE, NEXT_TAB, PREVIOUS_TAB, TAB_X (TAB_1…TAB_5), SETTINGS, SHORTCUTS, FUZZY_SEARCH, FS_LIST_VIEW, FS_DOTFILES, KB_PASSMODE, DEV_DEBUG, DEV_RELOAD.

Tip

Shortcuts are registered globally via globalShortcut while eDEX has focus and unregistered on blur, so they will not interfere with other applications when eDEX is in the background.

6.3 Command-line flags

eDEX accepts exactly two runtime flags (parsed in _renderer.js):

There are no other CLI flags and no environment-variable configuration.

7. Module Reference

The renderer's functionality is implemented as 18 ES6 classes in src/classes/, instantiated by initUI(). Each panel manages its own DOM and its own update timer (driven by window.si calls).

7.1 Core interaction modules

7.2 System-monitor modules (left column)

7.3 Network modules (right column)

7.4 Media / support modules

Note

Several modules guard their DOM updates in try/catch because the DOM can be torn down mid-update during a theme hot-swap (which reloads the UI). This is intentional defensive code, not a sign of error.

7.5 Inter-module communication

• The terminal client exposes oncwdchange / onprocesschange callbacks. FilesystemDisplay.followTab() subscribes to oncwdchange to re-read the directory; _renderer.js subscribes to onprocesschange to update the tab label.
• window.mods holds the live panel instances (clock, sysinfo, netstat, globe, …) so modules can reference each other (e.g. Conninfo reads window.mods.netstat.iface).
• window.term[n] holds the per-tab terminal clients; window.currentTerm is the active index.

8. Build & Distribution

8.1 Running from source

Linux / macOS

git clone https://github.com/GitSquared/edex-ui.git
cd edex-ui
npm run install-linux      # or rely on Xcode CLT on macOS
npm run start

install-linux runs npm install at the root and in src/, then electron-rebuild -f -w node-pty to recompile the native pty module against Electron's ABI.

Windows

Open cmd or PowerShell as administrator, then:

git clone https://github.com/GitSquared/edex-ui.git
cd edex-ui
npm run install-windows
npm run start

The legacy preinstall-windows step installs windows-build-tools, node-gyp, and points PYTHON at the bundled Python 2.7 for native compilation.

npm run start launches electron src --nointro.

8.2 npm scripts

Important

Because node-pty is a native module, you can only build artifacts for the host OS you are on — there is no cross-compilation. Run npm install (not the install-* variants) before build-*.

8.3 Packaging (electron-builder)

The root package.json build block defines the release matrix:

• asar: true — source packed into an asar archive.
• forceCodeSigning: false — binaries are unsigned.
• npmRebuild: true — native modules rebuilt during packaging.
• NSIS: oneClick: false, allowToChangeInstallationDirectory: true, deleteAppDataOnUninstall: true.
• publish: github — releases are published to GitHub.

8.4 The boot pipeline

prebuild-minify.js (via terser/clean-css) minifies JS and CSS before packaging so distributed binaries are smaller and obfuscated. file-icons-generator.js compiles the SVG icon submodules (Atom file-icons, devopicons, mfixx, font-awesome, bytesize) into src/assets/icons/file-icons.json plus a generated file-icons-match.js that maps filenames to icons by regex.

9. Operations

9.1 Deploying as a kiosk / touchscreen display

eDEX-UI is well-suited to a fullscreen kiosk. Recommended configuration:

{
  "forceFullscreen": true,
  "allowWindowed": false,
  "nocursor": true,
  "nointro": true,
  "theme": "tron-notype",
  "audio": false
}

• [x] forceFullscreen + allowWindowed:false locks the display fullscreen (F11 is intercepted).
• [x] nocursor:true hides the pointer for touch-only use.
• [x] nointro:true skips the boot animation on every restart.
• [x] A -notype theme hides the keyboard/filesystem for a cleaner monitor wall, if input isn't needed.
• [x] Launch with --nointro --nocursor to enforce kiosk behavior even before settings load.
• [x] Pre-seed settings.json and themes//keyboards/ in the user-data directory during provisioning.

Tip

eDEX opens on the primary display by default. Use the monitor setting (a display index) to target a specific screen in multi-monitor setups.

9.2 Logs and diagnostics

• The main process logs via signale to stdout/stderr (startup timing, terminal lifecycle, errors). Launch from a terminal to see them.
• The renderer forwards errors to the main log over IPC (ipc.send("log", "error", …)) and shows them as on-screen error modals.
• Open Chromium DevTools with Ctrl+Shift+I (enable the DEV_DEBUG shortcut first — it ships disabled).

9.3 Resetting configuration

To reset eDEX to defaults, quit it and delete (or rename) the user-data directory (§6). eDEX recreates default settings.json, shortcuts.json, and re-mirrors built-in assets on next launch.

9.4 Performance tuning

10. Troubleshooting (Operator Reference)

In-code error strings and their meaning:

Error: eDEX-UI crashed

An uncaught exception reached the main process. The dialog shows the underlying message; eDEX closes all ptys and exits with code 1. Launch from a terminal to capture the signale.fatal stack trace.

Error: Another instance of eDEX is already running. Cannot proceed.

The single-instance lock rejected a second launch. Use the existing window or fully quit it first.

Error: Configured cwd path does not exist.

settings.cwd points to a missing directory. Fix settings.json and restart.

Stuck at "Settings loaded!"

which(settings.shell) failed to resolve the shell to a path (issue #1168). Ensure the configured shell is installed and on PATH.

Error: ERROR: max number of ttys reached

All five terminal slots are occupied. Close a tab (exit its shell) before opening another.

Error: eval() is disabled for security reasons.

Expected — eval is intentionally disabled. If you see this it means some code (often an injected theme/plugin attempt) tried to call eval. Remove the offending customization.

Error: RAM Watcher Error: Bad memory values

systeminformation.mem() returned inconsistent totals on this platform. Usually transient; if persistent, it indicates a systeminformation incompatibility with the OS.

Error: fsDisp media displayer: unknown type <…>

The filesystem display tried to render a media type it doesn't handle. Open the file externally (Ctrl+click) instead.

Globe / IP blank, NetStat: Error parsing data from myexternalip.com

The external-IP lookup failed (offline, blocked, or proxied) (issues #964, #1135). The terminal is unaffected.

unable to verify the first certificate

TLS interception (corporate proxy). eDEX has no proxy support (issue #1050); network panels stay blank.

High CPU usage

Continuous graphs + globe + polling (issue #1169). Apply the performance levers in §9.4.

Layout overlap on ultrawide displays

Unusual aspect ratios are not fully supported (issues #832, #1162). Use a 16:9 display or extra_ratios CSS.

11. Code Quality & Conventions

12. Potential Improvements

Note

The project is archived, so these are observations for forks or maintainers rather than a roadmap.

• Migrate to the modern Electron security model. Move to contextIsolation:true + a contextBridge preload exposing a minimal API, and run the terminal bridge over IPC instead of an unauthenticated localhost WebSocket. This is a substantial rewrite but removes the broadest part of the attack surface.
• Replace the deprecated external-IP/GeoIP path. The myexternalip.com dependency and GeoLite2 download are common failure points; a configurable provider (or making the feature optional/offline) would improve reliability on restricted networks.
• Add proxy support. Honoring http_proxy/https_proxy (or an explicit proxy setting) would fix the corporate-network failures (#1050, #1103) instead of scrubbing the variables.
• Windows CWD tracking. Investigate a Windows-native mechanism (e.g. querying the pty child's working directory via the Win32 API) to remove the "detached" limitation.
• Reduce idle CPU. Throttle or pause graphs/globe when unfocused (currently backgroundThrottling:false), and make polling intervals configurable.
• Decouple modules from globals. Introduce a small event bus or dependency injection to reduce the window.* coupling and ease testing.
• Pin/refresh dependencies. node-pty 0.10, xterm 4, and Electron 12 are several major versions behind current; upgrading would bring security and rendering improvements (at the cost of API migration).

13. Quick Reference

Default ports

Default keyboard shortcuts

Config directory

Build commands

npm run install-linux   # or install-windows (admin)
npm run start           # run from source
npm install && npm run build-linux   # package for host OS (build-darwin / build-windows)

Key facts