# socketsupply/socket architecture

> Architecture diagram of the GitHub repository socketsupply/socket, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/socketsupply/socket
- Repository: https://github.com/socketsupply/socket

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Developer Environment"
        DevApp["Developer App (HTML/CSS/JS)"]:::external
        CLI["Socket CLI (Node.js)"]:::nodejs
        BuildScripts["Build & Automation Scripts (/bin)"]:::nodejs
        PackagingBins["Prebuilt Binaries (npm/packages)"]:::packaging
        Workspace["Workspace Config (pnpm‑workspace.yaml)"]:::packaging
    end

    DevApp -->|invokes| CLI
    CLI -->|runs| BuildScripts
    CLI -->|uses| PackagingBins
    CLI -->|uses| Workspace
    PackagingBins -->|outputs| Binary["Standalone Binary"]:::external
    Workspace -->|defines| Binary

    subgraph "Runtime (End‑User)"
        Desktop["Embedded WebView Host (src/desktop)"]:::native
        WebViewClient["WebView Runtime (src/runtime/webview)"]:::native
        RuntimeApp["Your App in WebView"]:::external
        API["JS API Facade (/api)"]:::nodejs
        subgraph "Native Runtime Core"
            CoreImpl["Runtime Core Implementation (src/runtime)"]:::native
            Services["Core Services (src/runtime/core/services)"]:::native
        end
        Platform["Platform Abstraction (src/runtime/platform)"]:::platform
        Extensions["Native Extension Loader (src/extension)"]:::native
        OS["OS Services (File IO, Sockets, Bluetooth)"]:::external
    end

    Binary -->|launches| Desktop
    Desktop --> WebViewClient
    WebViewClient --> RuntimeApp
    RuntimeApp -->|calls API| API
    API -->|IPC/FFI| CoreImpl
    CoreImpl --> Services
    CoreImpl -->|loads plugins| Extensions
    Services -->|system calls| Platform
    Platform -->|OS interaction| OS

    click CLI "https://github.com/socketsupply/socket/blob/master/npm/bin/ssc.js"
    click BuildScripts "https://github.com/socketsupply/socket/tree/master/bin/"
    click PackagingBins "https://github.com/socketsupply/socket/tree/master/npm/packages/"
    click Workspace "https://github.com/socketsupply/socket/blob/master/pnpm-workspace.yaml"
    click API "https://github.com/socketsupply/socket/tree/master/api/"
    click CoreImpl "https://github.com/socketsupply/socket/tree/master/src/runtime/"
    click Services "https://github.com/socketsupply/socket/tree/master/src/runtime/core/services/"
    click Platform "https://github.com/socketsupply/socket/tree/master/src/runtime/platform/"
    click Desktop "https://github.com/socketsupply/socket/tree/master/src/desktop/"
    click WebViewClient "https://github.com/socketsupply/socket/tree/master/src/runtime/webview/"
    click Extensions "https://github.com/socketsupply/socket/tree/master/src/extension/"

    classDef nodejs fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef native fill:#E6FFEA,stroke:#28A745,color:#28A745;
    classDef platform fill:#FFF4D6,stroke:#D69F00,color:#D69F00;
    classDef packaging fill:#F0E6FF,stroke:#6F42C1,color:#6F42C1;
    classDef external fill:#F6F8FA,stroke:#959DA5,color:#57606A;
```
