How socketsupply/socket works
Project Type and Purpose
• Type: A hybrid CLI + cross‑platform native runtime.
• Purpose: Package HTML/CSS/JS apps (and optional backend) into standalone desktop/mobile binaries, exposing “Node‑like” APIs (FS, TCP/UDP, Bluetooth, etc.) atop an embedded WebView.
A. Developer App
• Your HTML/CSS/JS/front‑end framework code (React, Vue, Svelte, plain JS).
B. Socket CLI (Node.js)
• JS scripts under /bin and npm/bin/ssc.js
• Reads your app, calls build scripts, orchestrates packaging.
C. JS API Facade Layer (/api)
• CommonJS and ESM modules (e.g. fs.js, http.js)
• Defines the public JS APIs you import in your code.
D. Native Runtime Core (/src/runtime + /src/core/services)
• C++/Kotlin/Objective‑C++ implementation of services: filesystem, networking, timers, IPC, crypto, service workers, workers.
• Uses a platform‑abstraction layer under /src/runtime/platform for Android, iOS, Windows, Linux, macOS.
E. Embedded WebView Host (/src/desktop, /src/webview)
• Bootstraps a native OS window + embeds Chromium/WebKit to render your HTML/JS.
F. Native Extension Loader (/src/extension)
• Loads and bridges native add‑ons (e.g. compiled plugins).
G. Packaging & Distribution (/npm/packages + pnpm-workspace.yaml)
• Prebuilt platform binaries for darwin‑x64, linux‑arm64, node‑integration, etc.
H. Build & Automation Scripts (/bin)
• Compile runtime, generate headers, docs, packaging.
1. Developer invokes socket CLI → CLI reads project manifest + your source.
2. CLI → Build Scripts (/bin) → Compiles & links native code for each target.
3. CLI → Bundles your app + /api stubs + chosen platform binary from /npm/packages.
4. Result: Standalone binary (contains Native Runtime + WebView + your code).
5. At runtime:
a. Embedded WebView loads your HTML/JS.
b. Your code imports a Socket API (e.g., import { readFile } from "fs").
c. API Facade Layer issues an FFI/IPC call into Native Runtime Core.
d. Runtime Core routes through platform layer → OS services (file IO, sockets, Bluetooth).
e. Responses come back via the IPC layer → your JS promise callbacks.
Architectural Patterns & Principles
• Facade Pattern: /api modules hide complexity of IPC/FFI.
• Adapter / Bridge Pattern: Platform‑abstraction in /src/runtime/platform.
• Plugin Architecture: Native add‑ons via /src/extension.
• Modular Service Layer: /src/runtime/core/services/* implements each API in isolation.
• Zero external deps: All code lives in‑repo; packaging scripts fetch no external libs at runtime.