# jlongster/electron-with-server-example architecture

> Architecture diagram of the GitHub repository jlongster/electron-with-server-example, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jlongster/electron-with-server-example
- Repository: https://github.com/jlongster/electron-with-server-example

## Overview

##### Project Type and Purpose
- This is an Electron-based desktop application that demonstrates embedding a standalone Node.js background server process for heavy or long-running tasks. It uses a custom IPC channel (via the node-ipc library) to avoid overloading Electron’s built-in IPC and to allow direct communication between the renderer UI and the backend.

##### File Structure Analysis
- Top-level files:
– index.js   → Electron “main” process bootstrap & window creation
– server.js   → entry-point for the forked Node.js backend
– server-handlers.js → business logic methods exposed by the backend
– client-app.js & client-index.html → UI code for the renderer
– server-dev.html  → debug UI for the backend in dev mode
– client-preload.js → preload script that exposes IPC APIs to the renderer
– client-ipc.js & server-ipc.js → socket-based IPC client/server wrappers
– find-open-socket.js → utility to pick a free domain socket name
- Pattern indicators:
– Electron’s main ↔ renderer pattern
– child_process.fork to spawn a true Node.js process
– node-ipc (UNIX domain socket) for direct renderer↔backend messaging
– Preload scripts to selectively expose Node APIs while sandboxing the UI

##### README Insights
- The README describes two runtime modes:
a) Development: backend runs in a hidden/visible renderer window (nodeIntegration enabled) for easy debugging.
b) Production: backend runs as a forked Node.js child process (no UI, pure background).
- It explains the motivation: avoid clogging Electron’s IPC and minimize main‐process hops.

a. Main Components to Represent
1) Electron Main Process
2) Renderer Process (Client UI)
3) Preload Layer (client-preload.js)
4) Node.js Backend Process
– In dev: as a hidden renderer window
– In prod: as forked child_process
5) IPC Socket (node-ipc)
6) Business Logic Handlers (server-handlers.js)

b. Relationships & Data Flows
– Main Process → spawns Renderer(Client) & Backend (fork or dev Window)
– Main Process → passes chosen socket name to both sides
– Renderer ←[preload bridge] client-ipc API ←→ Socket ←→ server-ipc ←→ Backend
– Client calls send(…) → socket → server-handlers → result → socket → client

c. Architectural Patterns & Principles
– Process Isolation: UI ↔ Backend in separate OS processes
– Explicit IPC channel avoids polluting Electron’s main IPC
– Preload sandbox: expose minimal Node API to the browser context
– Dev vs Prod branching: show conditional path where backend is a window vs forked process

d. Key Technologies & Libraries
– Electron (BrowserWindow, main/renderer model)
– Node.js child_process.fork
– node-ipc for Unix domain socket communication
– Preload scripts & contextIsolation considerations
– Standard web stack in UI (HTML/CSS/JS in client-app.js)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Electron Main Process
    subgraph "Electron Main Process" 
        direction TB
        Main["index.js"]:::main
    end

    %% Renderer Process
    subgraph "Renderer Process (Client UI)"
        direction TB
        ClientHTML["client-index.html"]:::renderer
        ClientApp["client-app.js"]:::renderer
        Preload["client-preload.js"]:::preload
        IPCClient["client-ipc.js"]:::ipc
    end

    %% IPC Utilities
    subgraph "IPC Utilities"
        direction TB
        SocketFinder["find-open-socket.js"]:::utility
        IPCServer["server-ipc.js"]:::ipc
    end

    %% Node.js Backend Process
    subgraph "Node.js Backend Process"
        direction TB
        ServerProd["server.js"]:::backend
        ServerDev["server-dev.html"]:::backend
        Handlers["server-handlers.js"]:::backend
    end

    %% Process Spawning & Setup
    Main -->|"spawn Renderer"| ClientHTML
    Main -->|"fork or create Dev Window"| ServerProd
    Main -->|"pass socket name"| SocketFinder

    %% Dev Mode: hidden window
    Main -.->|"dev"| ServerDev

    %% Preload exposes IPC client
    Preload --> IPCClient

    %% Renderer ↔ Backend IPC via socket
    IPCClient -->|"connect to socket"| SocketFinder
    SocketFinder -->|"provides socket path"| IPCClient
    SocketFinder -->|"provides socket path"| IPCServer
    IPCClient <-->|"socket messages"| IPCServer
    IPCServer --> ServerProd
    IPCServer --> ServerDev
    ServerProd --> Handlers
    ServerDev --> Handlers
    IPCServer -->|"invoke handlers"| Handlers

    %% Click Events
    click Main "https://github.com/jlongster/electron-with-server-example/blob/master/index.js"
    click ClientApp "https://github.com/jlongster/electron-with-server-example/blob/master/client-app.js"
    click ClientHTML "https://github.com/jlongster/electron-with-server-example/blob/master/client-index.html"
    click Preload "https://github.com/jlongster/electron-with-server-example/blob/master/client-preload.js"
    click IPCClient "https://github.com/jlongster/electron-with-server-example/blob/master/client-ipc.js"
    click IPCServer "https://github.com/jlongster/electron-with-server-example/blob/master/server-ipc.js"
    click SocketFinder "https://github.com/jlongster/electron-with-server-example/blob/master/find-open-socket.js"
    click ServerProd "https://github.com/jlongster/electron-with-server-example/blob/master/server.js"
    click ServerDev "https://github.com/jlongster/electron-with-server-example/blob/master/server-dev.html"
    click Handlers "https://github.com/jlongster/electron-with-server-example/blob/master/server-handlers.js"

    %% Styles
    classDef main fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef renderer fill:#E6FFEA,stroke:#28a745,color:#28a745;
    classDef preload fill:#FFF4D6,stroke:#E6A600,color:#E6A600;
    classDef ipc fill:#FFF0F0,stroke:#D73A49,color:#D73A49;
    classDef backend fill:#FFE4E1,stroke:#cb2431,color:#cb2431;
    classDef utility fill:#F0F0F0,stroke:#6a737d,color:#6a737d;
```
