WSS — WebSocket System

v0.0.1 Q2 2025 Complete

The Commitment

Node.js as distribution.

Node.js runs everywhere — x86, ARM, RISC-V. Docker Compose handles the services where we need full control. Licensed under AGPL-3.0 from day one — the software stack carries no proprietary weight and no vendor lock-in.

Your machine

Full platform, single node

Your cluster

Horizontal scaling across roles

Your datacenter

Distributed mesh with dedicated nodes

Any hardware

Gaming PC, NAS, laptop, Pi, old router

Zero-config deployment

One command. Interactive prompts. Topological dependency resolution.

        
          # Full platform, any device
          npx wss setup
          # Generates: docker-compose.yml, runtime-config.json,
          # nginx.conf, authorized_clients.json, secrets

What v0.0.1 establishes

Architecture independence from the first commit

WSS boots on any device that runs Node.js — a Raspberry Pi, a gaming desktop, a rack server. The CLI resolves service dependencies topologically, auto-injects consumed values between services, and generates all deployment configs from one interactive session. The platform adapts to your hardware, not the other way around. This runtime decision powers the unified protocol, the multi-role deployment, and ultimately full cluster control — all from one install command, one config file, any architecture.

v1.0.0 Q2–Q3 2025 Complete

The Foundation

Everything speaks the same language.

One typed protocol connects every service — authenticating users, uploading files, querying AI, publishing events. WebSocket or REST, the developer experience is identical.

Built on

v0.0.1 Node.js runtime v0.0.1 Docker Compose

30

services

252

actions

82

components

The service:action Protocol

One protocol. WebSocket or REST. Same types. Same auth. Self-describing actions.

        
          // One protocol for everything
          client.execute('iam', 'login', { username, password })
          client.execute('drive', 'listObjects', { bucket, prefix })
          client.execute('ai', 'generate', { model, messages })
          client.execute('schema', 'type', { id: 'Person' })
        
      

Four-tier architecture

Presentation82 Web Components + React/Angular/Vue wrappers, ECharts, Tiptap, GSAP

TransportDual WebSocket/HTTP — auto-fallback, offline queue, IndexedDB

Runtime30 services — Zod schemas, caching, rate limits, REST endpoints

InfrastructurePostgreSQL + TimescaleDB + pgvector, Valkey, SeaweedFS, Ollama

The UI Engine

82 Web Components. Framework wrappers for React, Angular, Vue. Everything a browser application needs — built in.

Custom Icon Fonts

Per-app Material Symbols subsetting. Select only the icons you need — the server generates a minimal WOFF2 font via fantasticon. Zero payload waste.

Animation Engine

JSON schema → GSAP timelines. Entrance, exit, and interaction animations defined as data. WCAG reduced-motion compliant. Shadow DOM safe.

Layer Management

Modals, drawers, toasts, tooltips, popovers — all rendered through wss-layers. Z-index bands, focus trapping, keyboard handling, backdrop management. One system for every overlay.

Chart Engine

Apache ECharts with data downsampling, performance monitoring, PNG/SVG export. JSON-configurable — the SDUI engine generates chart configs on demand.

Form Engine

15+ field types, conditional visibility, grid layout, action-driven option fetching, custom validation. One JSON schema → complete validated form.

Data Table

CSS Grid with sortable columns, row selection, bulk actions, custom cell rendering. Responsive grid with full ARIA — not HTML tables.

Built-in platform capabilities

LocalizationLazy-loaded locales, IDB cached, dynamic language switching, parameterized strings

Service WorkerOffline queue + replay, Workbox precaching, push notifications, background sync

Design Tokens3-tier system (primitive → semantic → component), dark mode, WCAG AA contrast validated

Rich Text EditorTiptap-based with multiple editing modes, syntax highlighting via Prism.js

Import Wizard8-step pipeline: upload → inspect → classify → structure → mapping → validate → relationships → review

Storage ManagerFile browser, drag-drop upload, quota tracking — full SeaweedFS integration

React HooksuseWssLayers, useWssData, useWssCrud, useWssSession, useWssAction, useWssStream, useTranslation

AccessibilityRoving tabindex, focus trapping, aria live regions, reduced-motion — WCAG AA tested

Infrastructure

ServerNode.js 22, Fastify 5, WebSocket

DatabasePostgreSQL + TimescaleDB, pgvector

CacheValkey — sessions, pub/sub, BullMQ

StorageSeaweedFS — S3 API compatible

AIOllama + multi-provider circuit breaker

NetworkNginx, Cloudflared, TincVPN

BuildTurborepo, pnpm 10, Stencil, Vite

What v1.0.0 delivers

A complete runtime — not just a protocol

Every action defines its own Zod schema, caching policy, rate limits, and REST endpoint — the registry is self-describing. Client libraries auto-discover available actions at connect time and cache the registry to IndexedDB. The Service Worker queues mutations when offline and replays them on reconnect. But the platform goes far beyond transport: the UI engine ships a layer management system for every overlay, an animation engine that converts JSON schemas to GSAP timelines, per-app icon font subsetting from 3,000+ Material Symbols, a form engine with conditional visibility, a chart engine for data visualization, and localization with IDB-cached locale switching. 82 components, 8 React hooks, full Service Worker — everything a browser application needs, with nothing to scaffold. This is the foundation that v1.5 identity authenticates through, v2.0 SDUI serves dynamically, and v3.0+ AI generates interfaces for.

v1.5.0 Q4 2025 Complete

Sovereign Auth

9 auth methods. 65 IAM actions. All shipping.

648 commits in one quarter. Web3 wallets across 107 chains, passkeys, TOTP, magic links, backup codes, device registry, OAuth connectivity, and step-up protocol for sensitive actions. All tokens encrypted at rest via pgcrypto + vault key.

Built on

v1.0 service:action protocol v1.0 WebSocket transport

Web3 Wallets107 chains: 52 EVM, 53 Cosmos, Solana, Arweave, ICP

PasskeysFIDO2/WebAuthn — phishing-resistant passwordless

TOTP 2FATime-based one-time passwords

Magic LinksFrictionless email-based access

Backup CodesRecovery when all else fails

Device RegistrySession tracking per device

Email / PasswordArgon2id hashing — baseline auth

OAuth Engine31 provider presets — runtime configurable

Step-Up ProtocolCryptographic proof for sensitive actions

3-Layer Connectivity Model

App registration → user authorization → prerequisite guards. All encrypted at rest.

Provider credentials registered → User authorizes & token stored → Token proxy auto-refreshes → Prerequisite guards enforce

Step-Up Protocol

Sensitive actions require cryptographic proof. Password-only is rejected.

Sensitive action triggered → Wallet: personal_sign() → Passkey: FIDO2 assertion → TOTP: 6-digit code → Action authorized

What v1.5.0 delivers

Complete identity sovereignty without third parties

Users authenticate with their own hardware — wallets they already control, passkeys stored on their devices, TOTP apps they choose. No Auth0, no Firebase, no Clerk. The service:action protocol carries every auth flow. OAuth tokens are encrypted at rest and auto-refreshed via token proxy — apps never touch raw credentials. The step-up protocol secures v3.0 terminal access and gates v3.0+ AI execution with cryptographic proof.

v2.0.0 Q1–Q2 2026 In Progress

Distribution & Dynamic Applications

Build applications, not boilerplate.

Four server roles, zero orchestrators, and a Server-Driven UI engine that makes every application dynamic. The server resolves routes to JSON-UI definitions, the renderer turns them into live interfaces — no per-app framework build, no static deployments.

Built on

v0.0.1 Docker Compose v1.0 service:action protocol v1.5 auth stack

Server-Driven UI — already operational

Routes resolve to JSON. JSON renders to interfaces. No framework per app.

Browser navigates /admin/users → graph:resolve matches route → Returns UIComponentDef JSON → wss-ui-renderer → live UI

graph:resolve

Three resolution paths: stored UI definition (instant), deterministic generation from entity schema, or AI fallback via vector search + LLM. Permission checks built in.

wss-ui-renderer

Recursive JSON→VDOM engine with Web Worker parsing. Concurrent data binding, conditional rendering via JSON-Logic, event bus integration for all interactions.

wss-router

Client-side routing with IndexedDB cache + background revalidation. Offline guard resolves from cached session, permissions, and route metadata.

Four roles, zero orchestrators

index.ts — API

Client-facing WebSocket/HTTP. PM2 cluster mode for load balancing.

worker.ts — Background

BullMQ job processing. Namespaced actions: service.worker:action.

media.ts — WebRTC

Mediasoup real-time audio/video streaming.

web3.ts — Decentralized

Libp2p peer discovery and mesh coordination.

Cluster without orchestrators

NetworkingTincVPN mesh — private network, no static IPs

DiscoveryValkey pub/sub — real-time peer liveness

RegistryPostgreSQL — node registration, capabilities, health

ProcessPM2 — cluster mode for API, fork mode for workers

SecurityIP-based auth bypass for VPN traffic, full auth for external

Monitoring & observability

Netdata integration with 7 server actions — system metrics rendered as SDUI charts.

Netdata Service

Per-node metrics aggregation, polling intervals, chart subscriptions, alarm tracking. The server queries Netdata and exposes data through the same service:action protocol.

Dynamic Dashboards

wss-chart generates ECharts configs from Netdata data via JSON-UI. CPU, memory, disk, network — any Netdata chart becomes a live dashboard widget through the SDUI engine.

NPM Packages

Every monorepo package published publicly. Install, compose, build your own stack.

Docker Images

Official images for every service role. Pull, configure, deploy anywhere.

Open Source

AGPL-3.0 licensed. No proprietary dependencies. Fork it, audit it, own it.

What v2.0.0 enables

Dynamic applications with full platform capabilities

The SDUI engine — graph:resolve, wss-ui-renderer, wss-router — is operational. Applications are JSON definitions served by the platform, not static builds deployed as separate services. The admin panel is actively migrating from Next.js to pure SDUI, proving the model: define routes and UI as data, the server generates everything else. Every dynamic application inherits the full v1.0 UI engine — layer management, animation engine, chart engine, form engine, localization, icon fonts, and offline-first Service Worker. Add a new entity, get a full CRUD interface. Connect a new Netdata instance, get instant monitoring dashboards. The cluster infrastructure distributes these apps across nodes without Kubernetes, and the v3.0 control plane manages them as a single interface.

v2.5.0 Q3 2026 Planned

The Primitives

Build generic capabilities, not specific features.

Two pillars: a universal task management system that tracks all async jobs across the cluster, and a Web3-aware security layer that lets actions declare their auth requirements. v3.0 is built entirely from these primitives.

Built on

v1.0 service:action protocol v1.0 BullMQ queues v2.0 server roles

Generic Task Management

Worker hooks — onJobQueued, onJobActive, onJobCompleted, onJobFailed — persist all job state into a central tasks service. Query any job by service, node, status, or user. The v3.0 task runner is this API with a UI.

Web3-Aware Security Layer

Declarative requiredPermission and stepUp config on every action definition. Central enforcement in dispatchMessage — zero per-action security code.

Action Composition

Primitives call infrastructure. Composites call primitives via context.callService().

        
          // Composite action — calls primitives, not infrastructure
          const { embedding } = await ctx.callService('ai', 'embed', { text })
          const { results } = await ctx.callService('schema', 'searchTypes', { embedding })
          return ctx.callService('ai', 'generate', { prompt, results })

What v2.5.0 unlocks

Composable primitives that eliminate custom code

The task management system gives every async job — across every v2.0 node — a queryable lifecycle. The Web3 security layer lets any action declare its auth requirements as a single property instead of per-handler code. And the composition API lets you chain service:action calls into reusable workflows with introspectable call graphs, action-level caching, and rate limiting. The v3.0 task runner is tasks:list with a UI. The v3.0+ AI planner generates composite action configurations from natural language.

v3.0.0 Q4 2026 – Q1 2027 Planned

The Control Plane

Create applications from the admin interface.

No Next.js. No static builds. No per-app Docker services. The server renders dynamic HTML shells, resolves routes to SDUI definitions, and serves every application from one process. Create a new app from the admin UI — define its routes, its entities, its permissions — and it’s live on its own subdomain.

Built on

v1.0 WebSocket transport v1.5 step-up protocol v2.0 SDUI engine v2.5 task management

Dynamic App Server

Host header → app ID resolution → dynamic HTML shell. Stencil bundles served from SeaweedFS. Universal Service Worker. One wss-server instance handles all applications — no per-app Docker service needed.

Application Scaffolding

Create apps from the admin panel: name, subdomain, icon, routes, permissions. wss-root boots the SDUI engine, graph:resolve serves every page. 27 vectorized domain blueprints — grounded in Schema.org — let the platform scaffold any application type: project management, finance, e-commerce, hospitality, logistics, and beyond. Add entities, get instant CRUD. The blueprints are composable primitives, not rigid templates — combine them without limits.

Interactive Console

Web3 session → wallet sign → full terminal. cli:execute bridges PTY over Unix Socket to the wss-cli daemon. Direct shell access to any node via xterm.js.

Task Runner

Click → Web3 step-up (single-use signature) → cli.worker:execute queued to BullMQ → live output. The generic TaskViewer from v2.5 renders it — no new UI needed.

What v3.0.0 completes

Unlimited applications from a single platform

Every application — admin, portal, or anything you create — is a set of route definitions served by the same SDUI engine. Add more services, more actions, more components — every app on the platform benefits immediately. No rebuilds, no redeployments, no framework lock-in. The admin console, terminal, and task runner prove the pattern: composed entirely from v1.5 auth, v2.0 SDUI, and v2.5 primitives. Every surface reuses proven building blocks — and gives v3.0+ AI a full control plane to operate through.

v3.0+ Q2 2027+ Vision

The Agentic Future

Agentic workflows for everyone.

13 AI actions and the semantic layer are already shipping. Multi-provider routing, pgvector search, and Schema.org introspection form the foundation. What comes next: AI that builds applications, generates interfaces, and operates the entire platform — with full source traceability.

Built on

v1.0 252 actions v1.5 step-up protocol v2.5 action composition v3.0 app platform

Already shipping

Multi-Provider AI

Ollama local, OpenAI, Anthropic, OpenRouter (100+ models), Gemini, Mistral. Circuit breaker with automatic failover. Model registry resolves abstract selectors to concrete providers.

Vector Search

pgvector with cosine distance. schema:vectorize chunks documents, embeds via Ollama, stores with metadata. schema:searchTypes finds by cosine similarity with hybrid JSONB filtering.

Schema.org Semantic Layer

83 Schema.org types across 27 domain blueprints — vectorized on boot. schema:type resolves class + properties, cached 7 days. Self-healing auto-seed. 13 schema actions power classification, mapping, and search.

27 domain blueprints — vectorized on boot

Every blueprint is embedded and stored in pgvector at startup. The LLM doesn’t guess — it searches 147 entity definitions across 83 Schema.org types to scaffold, classify, and map data for any domain. Not limits — composable primitives that work together no matter the situation.

Project & Agile Finance & Billing Commerce & Logistics CRM & Marketing Hospitality Healthcare Education & LMS Real Estate Fleet & Transport Manufacturing HR & Recruitment Legal Insurance Agriculture Construction IT & DevOps Event Management Compliance & Audit Content & Media Nonprofit Booking & Appointments Service & Warranty + Your domain

Scaffold any application

Project management? Financial app? Chat? Storage? Web shop? Hotel and restaurant? Logistics? Stock management? All of the above? The AI searches vectorized blueprints, composes matching entities, and generates a full SDUI application with routes, forms, and CRUD — no framework code, just JSON definitions rendered by the v2.0 SDUI engine. The idea is not to create limits, but primitives that compose no matter the situation.

Curate imported data

Import a WordPress site with a blog, shop, and pages — schema:classifyData identifies each record against the vectorized vocabulary, schema:mapFields aligns columns to Schema.org properties, and the 8-step import wizard guides the rest. The same pipeline curates any external dataset into blueprint-native entities — properly mapped to Schema.org structure for agentic JSON-UI generation.

The vision

Phase 1: Self-Awareness

registry:listActions + registry:getActionDefinitions give the LLM full introspection of all actions, payloads, and service topology.

Phase 2: Planner & Executor

JSON execution plans with staged confirmation. Two-tier policy: simple actions auto-approve, destructive actions require step-up via v1.5 protocol.

Phase 3: Context Engine

Hierarchical MapReduce for >100K token reasoning. Distributed across v2.0 worker nodes. TTL-enforced prompt persistence.

AI-generated applications

Not features — primitives. The SDUI engine renders JSON, blueprints define structure, vector search finds the match. These compose without limits: one app or twenty, one domain or all 27. The same blueprints that scaffold applications also power agentic JSON-UI building — AI-driven interface generation grounded in semantic vocabulary.

wss-service-ui

One-liner action interface generator. Point at any service:action, get a complete form with validation, submission, and response handling.

wss-entity-view

Universal CRUD interface. Point at any entity slug, get list/create/edit/delete with schema-driven field rendering.

What v3.0+ envisions

A platform where anyone can build anything

Every developer starts a new project with the same grind — auth, file storage, database, API layer, admin panel, deployment. WSS ships all of it. The LLM knows every action, every schema, every service state. It generates JSON execution plans from natural language, stages them for human confirmation through the step-up protocol, and runs them through the action composition API. Add more services, more actions, more components — the platform grows and every application on it benefits. The entire stack is open source. Every dependency is traceable. Every action is introspectable. The community can extend, audit, and enhance everything — because the code is the product, and the product is the code.