RCWeb Architecture Overview

A deep analysis of Java class linking and the stateless virtual room model.

1. Core Architecture & Class Linking

The RCWeb system is built on a streamlined, high-performance architecture centered around real-time communication between browsers. Below is a map of the primary Java classes and how they link together.

classDiagram Main --> HttpServer : creates & configures HttpServer --> HttpHandler : creates per connection HttpHandler --> SuperSocket : enhances with TLS SuperSocket --> HttpRequest : reads HTTP request HttpRequest --> RootResponder : delegates RootResponder --> HttpResponse : generates RootResponder ..> ClientWebSocketHandler : upgrades to websocket HttpResponse --> SuperSocket : writes HTTP response RootResponder ..> RoomManager : queries RoomManager "1" *-- "many" Room : manages Room "1" *-- "many" Client : contains ClientRequest --> Room ClientRequest --> Client ClientWebSocketHandler --> ClientRequest : reads websocket frame ClientWebSocketHandler ..> SuperSocket : writes websocket frame Client "1" *-- "many" ClientCommand : queues

HttpHandler

Created by the HttpServer for each incoming connection. It runs in its own virtual thread, managing the lifecycle of an HTTP request. It parses the HttpRequest, delegates it to a responder (e.g., RootResponder), and writes back the HttpResponse.

SuperSocket

A wrapper around the standard Java Socket that provides enhanced capabilities, such as TLS sniffing and connection lifecycle management.

HttpRequest & HttpResponse

Represent the standardized HTTP request and response models. HttpRequest is parsed from the SuperSocket's input stream, while HttpResponse is generated by the responder and written back over the network.

RoomManager

A singleton service that acts as the central registry for all active workspaces (Rooms). It maintains a concurrent map of roomId strings to Room objects. It also runs a background maintenance thread to prune inactive connections and cleanly close all sockets during JVM shutdown.

Room

Represents a virtual environment where multiple browsers can interact. A Room maintains a list of attached Client objects. It provides the crucial broadcast() method, which routes a ClientCommand (containing JavaScript payloads) to specific target clients within the room.

Client

Represents an active browser connection within a Room. It holds a ClientRequest containing metadata (IP, user-agent, timers) and a thread-safe queue of ClientCommand objects. Virtual threads waiting for outgoing WebSocket traffic synchronize on this object via wait() and notifyAll().

ClientWebSocketHandler

Upgrades the HTTP request and handles the active WebSocket lifecycle. It runs an infinite loop within a virtual thread, blocking on client.wait(IDLE_PERIOD) until a new command is queued. When data is received from the browser, it reads the raw byte array, parses it into a ClientCommand, and dispatches it via room.broadcast().

ClientCommand

A lightweight wrapper representing a message to be sent to browsers. It encapsulates target identifiers (which browsers should receive this) and the raw byte payload of the JavaScript to be executed on the client-side.

2. Virtual Rooms & Shared JavaScript

A fundamental concept of the RCWeb architecture is the Virtual Room. Rather than each browser maintaining an isolated session with the server, browsers connect to a shared Room using a unique ID in their URL.

The server acts purely as a message broker. When an event happens in one browser (e.g., a user clicks a button or moves a slider), it sends a WebSocket message containing executable JavaScript. The backend ClientWebSocketHandler catches this, wraps it in a ClientCommand, and asks the Room to broadcast it.

The Room forwards this JavaScript payload into the command queues of other relevant Clients in the same room. The server pushes this JavaScript down their WebSockets, and the receiving browsers execute it immediately using eval() or script injection. This allows browsers to seamlessly share state and replicate user interfaces in real-time.

3. Stateless Design & Performance Benefits

RCWeb embraces a heavily stateless backend design.

Radical Simplicity
The Java server does not maintain any application state, business logic rules, or persistent database state. It is entirely unaware of the meaning of the messages it routes. This removes the need for complex state synchronization logic, making the backend incredibly simple, robust, and easy to test.
Extreme Performance
By delegating application logic to the client's browser, the server's CPU and memory footprint are negligible. The server only needs to hold tiny Client objects and a few bytes for the ClientCommand queues. Instead of consuming expensive OS threads for each WebSocket connection, ClientWebSocketHandler leverages Java Virtual Threads. Handlers simply call client.wait(), consuming virtually no resources while waiting for traffic. This architecture allows a single small instance to effortlessly handle thousands of concurrent, real-time web socket connections.