# How the Server Edition of nodeterm Differs Architecturally from the Electron Version

> Discover the architectural differences between nodeterm Server Edition and its Electron version. Learn how the Server Edition uses a two-process Node HTTP/WebSocket model for a lightweight approach.

- Repository: [eneskirca/nodeterm](https://github.com/eneskirca/nodeterm)
- Tags: architecture
- Published: 2026-08-25

---

**The Server Edition replaces Electron’s three‑process main/preload/renderer architecture with a lightweight two‑process Node HTTP/WebSocket server model, while both implementations plug into the same platform‑agnostic core services through an identical `CorePlatform` interface.**

nodeterm is structured around a shared *core* layer (`src/core/`) that houses all platform‑agnostic services such as PTY management, workspace persistence, and agent hooks. The repository ships two distinct *platform* layers that adapt this core to their respective environments: the Electron version for desktop users and the Server Edition for browser‑based, headless deployments. Understanding how the Server Edition of nodeterm differs architecturally from the Electron version highlights a deliberate trade‑off between native OS capabilities and universal remote accessibility.

## Core Architecture and the Platform Adapter Pattern

All business logic resides in `src/core/`, which remains identical across both editions. Platform‑specific behaviors are abstracted behind the `CorePlatform` interface, implemented separately by each edition.

- **Electron adapter**: [`src/main/platform-electron.ts`](https://github.com/eneskirca/nodeterm/blob/main/src/main/platform-electron.ts) provides desktop‑specific integrations using Electron’s `app`, `BrowserWindow`, and `safeStorage` APIs.
- **Server adapter**: [`src/server/platform-server.ts`](https://github.com/eneskirca/nodeterm/blob/main/src/server/platform-server.ts) provides server‑specific integrations including an HTTP server, WebSocket handling, and file‑based secret storage.

This adapter pattern ensures that features such as terminal session management and workspace state remain consistent regardless of the deployment target.

## Process Model Comparison

The most significant architectural divergence lies in the process boundary design.

### Electron Desktop Version (Three‑Process Model)

The Electron version runs a classic Chromium‑embedded architecture:
1. **Main process** (`src/main/`) – Node.js/Electron runtime that initializes the core services and creates browser windows.
2. **Preload script** (`src/preload/`) – Isolated context that bridges the main process and renderer using Electron’s `contextBridge`.
3. **Renderer process** (`src/renderer/`) – Chromium environment hosting the React UI.

The main process instantiates the platform adapter at [`src/main/platform-electron.ts`](https://github.com/eneskirca/nodeterm/blob/main/src/main/platform-electron.ts), granting direct access to native modules such as `node‑pty` and OS‑level keychain services.

### Server Edition (Two‑Process Model)

The Server Edition eliminates the main and preload layers, replacing them with a headless stack:
1. **Node HTTP + WebSocket server** (`src/server/`) – Runs the core services and exposes a WS‑RPC bridge defined in [`src/shared/rpc.ts`](https://github.com/eneskirca/nodeterm/blob/main/src/shared/rpc.ts).
2. **Browser client** – Connects remotely; the React UI renders in a standard web browser rather than an embedded Chromium window.

The server implements `CorePlatform` via [`src/server/platform-server.ts`](https://github.com/eneskirca/nodeterm/blob/main/src/server/platform-server.ts), handling requests over WebSocket connections rather than Electron’s IPC channels.

## Inter‑Process Communication Bridges

Despite differing transport mechanisms, both editions expose an identical `window.nodeTerminal` API to the frontend.

**Electron bridge**: The preload script at [`src/preload/index.ts`](https://github.com/eneskirca/nodeterm/blob/main/src/preload/index.ts) uses `contextBridge` to inject a narrow, privileged API into the renderer’s global scope.

**Server bridge**: The browser client loads a WebSocket‑RPC client from `src/renderer/bridge/` that connects to `ws://localhost:3000`. This bridge mirrors the preload API, allowing the React UI to call core methods transparently without modification.

```typescript
// src/renderer/bridge/index.ts – Browser client initialization
import { createRpcClient } from '@shared/rpc';
const rpc = createRpcClient('ws://localhost:3000');
window.nodeTerminal = rpc; // Identical interface to desktop version

```

## OS Integration and Capability Gaps

The Server Edition sacrifices native OS integrations in exchange for headless operation and remote accessibility.

- **Secret storage**: Electron uses the OS keychain via `safeStorage`; the Server Edition stores authentication keys as raw files (`node-auth-key.bin`) in the working directory.
- **Native modules**: Features relying on OS‑level helpers—such as canvas control and context menu links—are **disabled** or stubbed in the Server Edition according to [`docs/SERVER.md`](https://github.com/eneskirca/nodeterm/blob/main/docs/SERVER.md).
- **Notification host**: Unlike the Electron version, which requires a visible window for background tasks, the Server Edition can act as a **headless notification host**, processing updates without a UI surface.

## Deployment and Entry Points

Starting the two editions requires distinct npm scripts and environment preparations.

**Electron Version** (requires Node ≥ 20 and tmux):

```bash
npm install    # Rebuilds native modules

npm run dev    # Launches Electron with hidden Chromium window

```

**Server Edition** (requires Node 22+ and tmux):

```bash
npm run server:dev   # Builds renderer and starts headless HTTP/WS server

```

Once the server is running, users access nodeterm from any modern browser by navigating to the server URL (default `http://localhost:3000`), where the WebSocket bridge initializes automatically.

## Summary

- **Shared core**: Both editions use identical logic in `src/core/` for PTY, workspace, and agent management.
- **Adapter pattern**: [`src/main/platform-electron.ts`](https://github.com/eneskirca/nodeterm/blob/main/src/main/platform-electron.ts) and [`src/server/platform-server.ts`](https://github.com/eneskirca/nodeterm/blob/main/src/server/platform-server.ts) implement the same `CorePlatform` interface for their respective environments.
- **Process reduction**: Server Edition removes the main and preload processes, replacing them with a Node HTTP/WebSocket server (`src/server/`).
- **Transport swap**: Electron’s `contextBridge` ([`src/preload/index.ts`](https://github.com/eneskirca/nodeterm/blob/main/src/preload/index.ts)) becomes a WebSocket‑RPC bridge ([`src/shared/rpc.ts`](https://github.com/eneskirca/nodeterm/blob/main/src/shared/rpc.ts) and `src/renderer/bridge/`).
- **Feature limitations**: Server Edition lacks OS keychain access, canvas controls, and context links, storing secrets in flat files instead.
- **Headless capability**: Server Edition supports fully headless operation as a notification host, while Electron requires a window process.

## Frequently Asked Questions

### What are the minimum Node.js requirements for each edition?

The Electron version requires Node.js ≥ 20, while the Server Edition requires Node.js 22 or newer. Both require tmux to be installed on the host system for terminal session management.

### Can the Server Edition access native OS features like the keychain?

No. The Server Edition lacks Electron’s privileged APIs and cannot access the OS keychain. It stores sensitive data as raw files (`node-auth-key.bin`) in the application directory, whereas the Electron version uses the platform’s secure credential store via `safeStorage`.

### Is the React UI code identical between the desktop and Server versions?

Yes. The React components in `src/renderer/` are shared across both editions. The Server Edition loads these components in a standard browser environment, while the Electron version hosts them inside a Chromium window. The UI communicates with the core through `window.nodeTerminal` in both cases, abstracting whether the underlying transport is Electron’s IPC or a WebSocket connection.

### How does the Server Edition handle background tasks without a window?

The Server Edition runs as a persistent Node.js process capable of acting as a **headless notification host**. Unlike the Electron version, which requires a renderer process for background work such as update checks, the Server Edition manages these tasks within the main HTTP/WebSocket server process, allowing it to operate on remote servers without a display.