CollaboKeys Architecture: Electron, Socket.IO, and Native Emulation

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tinkerer9/CollaboKeys/llms.txt

Use this file to discover all available pages before exploring further.

​

Module Breakdown

​

src/main.js — Electron entry point

1. Reads Variables.electronPackaged and Variables.userDataPath from app.isPackaged and app.getPath("userData") before any other module loads, so downstream modules can locate log files and the compiled helper.
2. Creates a BrowserWindow (1200×800, dark background, no node integration) and immediately loads the splash screen from src/public/splash/index.html.
3. Calls startServer() from server.js, waits for the configured splashScreenTime, then navigates the window to http://localhost:{port}/admin.
4. Calls systemPreferences.isTrustedAccessibilityClient(true) to prompt for the macOS Accessibility permission required for keyboard emulation.
5. Optionally calls powerSaveBlocker.start("prevent-display-sleep") to keep the display awake during a session.

​

src/server.js — Core server

• Creates the HTTP server via Router.createServer() and wraps it in a Socket.IO Server instance.
• Creates the /admin Socket.IO namespace: const admin = io.of("/admin").
• Stores both namespace references in Variables and registers the AdminPageTransport on the admin namespace so Winston logs are streamed to admin clients in real time.
• Handles the player lifecycle on the default / namespace: connection → setName → keydown/keyup → disconnect.
• Handles the admin lifecycle on /admin: connection → optional auto-authentication → authenticate → command → disconnect.
• Exports startServer(), which tries each port from config.json in order (falling back to port 0 for a random OS-assigned port) and resolves with the bound port number.

​

src/router.js — HTTP server

​

src/client.js — Player and Admin classes

• Holds a socket reference, a numeric id (auto-incremented), a name (initially null), and a waitingRoom flag initialised from config.json.
• setName(name) validates length (min/max from config) and the configured regex, returning an integer result code: 0 = success, 1 = too short, 2 = too long, 3 = regex fail.
• canType() returns true only when the player has a name set and is not in the waiting room.
• destroy() calls Manager.removePlayer() and Key.freeAssignment() to clean up all held keys.

• Holds a socket, an id, and an authenticated flag.
• authenticate() sets the flag to true and joins the "admin" Socket.IO room so the AdminPageTransport can broadcast logs.

​

src/manager.js — Global player registry

• addPlayer(pid, player) — called from Player constructor
• removePlayer(pid) — called from Player.destroy()
• getPlayerByPid(pid) — used by keycodes.js to resolve display names
• isPlayer(pid) — used by console.js for command validation
• getAllPlayers() — returns Object.values(players) for iteration
• getPlayerCount() — returns the total connected player count

​

src/type.js — Keyboard emulation logic

• handleKeydown(player, key) — runs canType(player, key, true), increments the global per-minute counter, emits keyReserved to the player if this is a new assignment, logs the event, and calls keyboard.down(keycode) (or keyboard.press if held keys are disabled).
• handleKeyup(player, key) — runs canType(player, key, false) (skips emulation-disabled check for keyups) and calls keyboard.up(keycode).
• canType(player, key, down) — performs all precondition checks in order:
  1. player.canType() — name set and not in waiting room
  2. Variables.allowEmulation — global emulation toggle (keydown only)
  3. Global keypress rate limit (maxKeypressesPerMinute from config)
  4. keyExists(key) — key is in the keycodes table
  5. keyEnabled(key) — key is not disabled by admin
  6. Key.keyAllowed(key, player.id) — key is unassigned or already owned
  7. Config.player.maxReservedKeys — per-player key cap

​

src/key.js — Key assignment state

• keyAllowed(key, id) → [allowed: boolean, isNew: boolean]
  • If unassigned and Variables.allowReservation is true: assigns and returns [true, true]
  • If already assigned to this player: returns [true, false]
  • If assigned to another player: returns [false, false]
  • If unassigned but reservation is disabled: returns [false, true]
• assignKey(key, id) / revokeKey(key) — set/clear index [3]
• freeAssignment(id) — clears all keys owned by id (called on disconnect)
• revokeAllKeys() — clears every assignment (console key revoke all)
• keyCount(id) — counts a player’s current reservations for the maxReservedKeys check

​

src/public/alias.js — Browser key name normalization

// Examples of what the aliases table contains:
"A" → "a",  "B" → "b",  // uppercase → lowercase
"!" → "1",  "@" → "2",  // shifted number row → base digit
"_" → "-",  "+" → "=",  // shifted symbol → base symbol
"{" → "[",  "}" → "]",
":" → ";",  "\"" → "'",
"<" → ",",  ">" → ".",  "?" → "/"

​

src/keycodes.js — Key definitions

// "keyName": [keyCode, "humanName", enabled, assignedPlayer]
"a":          [0,   "a",           true,  null],
"Enter":      [36,  "return",      true,  null],
"ArrowLeft":  [123, "left arrow",  true,  null],
"Shift":      [56,  "shift",       false, null], // disabled by default

​

src/console.js — CLI command handler

​

src/log.js — Winston logging

• In development: logs/ relative to the project root
• When packaged: {app.getPath("userData")}/logs/

​

src/utils.js — Utilities

• sendLog(client, content, format) — emits a log event on the client’s own socket.
• broadcastLog(client, content, format) — emits a log event to every other connected socket (not the sender).
• getLocalIP() — iterates os.networkInterfaces() to find the first non-internal IPv4 address.
• getURI() — combines getLocalIP() and Variables.serverPort into a full http:// URL.
• escapeHTML(str) — replaces &, <, >, ", ' with HTML entities for safe log rendering.

​

src/variables.js — Shared mutable state

{
  mainNamespace:    null,   // Socket.IO default namespace (set in server.js)
  adminNamespace:   null,   // Socket.IO /admin namespace (set in server.js)
  serverPort:       null,   // bound port (set after startServer() resolves)
  electronPackaged: null,   // app.isPackaged (set in main.js before other imports)
  userDataPath:     null,   // app.getPath("userData") (set in main.js)
  allowEmulation:   <config>,   // global emulation toggle
  allowReservation: <config>    // global auto-reservation toggle
}

​

src/emulate/keyboard.js — KeyboardHelper class

const keyboard = new KeyboardHelper();
keyboard.down(keycode);   // sends EVENT_KEY_DOWN packet
keyboard.up(keycode);     // sends EVENT_KEY_UP packet
keyboard.press(keycode);  // sends EVENT_KEY_PRESS packet
keyboard.stop();          // drains stdin and kills the process

• Development: path.join(__dirname, "helper") — i.e. src/emulate/helper
• Packaged: path.join(process.resourcesPath, "helper") — bundled by electron-builder

​

src/emulate/helper.c — Native C keyboard helper

​

Binary IPC Protocol

Byte offset:  0        1        2
              [keycode_lo] [keycode_hi] [event_type]
              └──── uint16 LE ────┘     └─ uint8 ──┘

const packet = Buffer.alloc(3);
packet.writeUInt16LE(keycode, 0);   // bytes 0–1
packet.writeUInt8(eventType, 2);    // byte 2
this.helper.stdin.write(packet);

typedef struct __attribute__((packed)) {
    uint16_t keycode;
    uint8_t  event_type;
} KeyEvent;

​

Key Data Flow

Browser keydown event
  → socket.emit("keydown", key)                   [client browser]
  → io.on("connection") → socket.on("keydown")    [server.js]
  → Type.handleKeydown(player, key)               [type.js]
  → canType(player, key, true)                    [type.js]
      → player.canType()                          [client.js]
      → Variables.allowEmulation check            [variables.js]
      → rate limit check                          [type.js]
      → keyExists(key), keyEnabled(key)           [type.js / keycodes.js]
      → Key.keyAllowed(key, player.id)            [key.js]
  → keyboard.down(keycodes[key][0])               [type.js]
  → KeyboardHelper.sendEvent(keycode, EVENT_KEY_DOWN)  [keyboard.js]
  → helper.stdin.write(3-byte packet)             [keyboard.js]
  → read() loop in main()                         [helper.c]
  → CGEventCreateKeyboardEvent(NULL, keycode, true)
  → CGEventPost(kCGHIDEventTap, event)            [helper.c]

​

Socket.IO Namespaces