OOCSI Architecture

OOCSI is designed as a lightweight, message-based prototyping middleware and event bus tailored for physical computing, interaction design, and distributed multi-device systems. At its core, OOCSI connects heterogeneous devices and programming environments—from low-power microcontrollers and Python scripts to web dashboards and mobile devices—without requiring complex networking configurations.

---

Hub-and-Spoke Topology

OOCSI operates on a hub-and-spoke architecture. A central OOCSI server acts as the message broker, maintaining client registries, managing channel subscriptions, routing direct and broadcast messages, and evaluating server-side expressions.

flowchart TD
    subgraph Clients["Connected OOCSI Clients"]
        MCU["Embedded (ESP32 / Arduino)<br/>Port 4444 TCP"]
        PY["Python Script / ML<br/>Port 4444 TCP"]
        JAVA["Processing / Java<br/>Port 4444 TCP"]
        WEB["Browser / Web App<br/>Port 9000 WebSocket"]
        REST["HTTP Webhook / cURL<br/>Port 9000 REST"]
    end

    subgraph Server["OOCSI Server (oocsi-web)"]
        TCP_ADAPTER["NIO TCP Socket Service (Port 4444)"]
        HTTP_ADAPTER["Play HTTP & WebSocket Engine (Port 9000)"]
        ROUTER["Message Router & Channel Directory"]
        STATE["Presence, Retention & Timers"]
        FILTER["EvalEx In-Flight Filter / Transform Engine"]
    end

    MCU <--> TCP_ADAPTER
    PY <--> TCP_ADAPTER
    JAVA <--> TCP_ADAPTER
    WEB <--> HTTP_ADAPTER
    REST <--> HTTP_ADAPTER

    TCP_ADAPTER <--> ROUTER
    HTTP_ADAPTER <--> ROUTER
    ROUTER <--> STATE
    ROUTER <--> FILTER

---

Dual Network Port Architecture

flowchart TD
    subgraph Clients["Heterogeneous Clients"]
        C_ESP["Embedded C++ / ESP32<br/>(oocsi-esp)"]
        C_PY["Python Client<br/>(oocsi-python)"]
        C_JAVA["Java / Processing<br/>(oocsi)"]
        C_WEB["Web Browser / PWA<br/>(oocsi-web.js)"]
        C_REST["HTTP Client / cURL<br/>(REST API)"]
    end

    subgraph Ports["Server Network Ports"]
        PORT_4444["Port 4444 (TCP Socket)<br/>Plaintext Line Protocol"]
        PORT_9000["Port 9000 (HTTP / WebSockets)<br/>Play / Pekko Engine"]
    end

    subgraph Core["OOCSI Broker Core"]
        ROUTER["Message Router & Channel Directory"]
        TIMERS["Heartbeat & Timers Queue"]
        EVAL["In-Flight EvalEx Engine"]
    end

    C_ESP -->|Raw TCP| PORT_4444
    C_PY -->|Socket TCP| PORT_4444
    C_JAVA -->|Socket TCP| PORT_4444

    C_WEB -->|WebSocket /ws| PORT_9000
    C_REST -->|REST /send & SSE /subscribe| PORT_9000

    PORT_4444 <--> ROUTER
    PORT_9000 <--> ROUTER
    ROUTER <--> TIMERS
    ROUTER <--> EVAL

The OOCSI server (oocsi-web) exposes two primary network interfaces to accommodate different runtime environments:

1. Native TCP Socket Interface (Port 4444)

• Target Platforms: Java, Processing, Python, C++/Arduino, MicroPython, Max/MSP, PureData.
• Characteristics: Persistent, low-latency TCP socket connection.
• Message Formats: Plaintext line protocol supporting JSON strings (sendjson), Base64 Java serialization (send), or raw strings (sendraw).

2. HTTP & WebSocket Interface (Port 9000)

• Target Platforms: Web browsers, progressive web apps (PWAs), Node.js applications, third-party webhooks.
• Endpoints:
  • /ws: Full duplex WebSocket endpoint for web applications (oocsi-web.js).
  • /subscribe/<channel>: Server-Sent Events (SSE) streaming endpoint for lightweight browser and shell subscribers.
  • /send/<channel>/<data>: RESTful trigger endpoint for webhooks and QR-code scanners.
  • /dashboard & /network: Interactive web dashboard and real-time network visualizer.
  • /metrics: Real-time server performance and connection statistics.

---

Cross-Protocol Bridging

A central strength of OOCSI is its protocol translation layer:

• When an ESP32 microcontroller on a raw TCP socket sends a message to channel lighting, the server automatically forwards the message to a browser listening over WebSockets, a Python script subscribed on TCP, and an HTTP client listening via Server-Sent Events.
• All payloads are serialized to standardized JSON objects containing sender, recipient, timestamp, and a data dictionary.

---

Internal Server Architecture

The OOCSI server engine is designed for rapid prototyping with robust failure isolation:

1. NIO Socket Engine: Employs non-blocking Java NIO channels to handle multiple concurrent microcontroller and desktop socket connections with minimal resource usage.
2. Actor-Based WebSockets: The web tier (oocsi-web) uses asynchronous actor flows (Pekko/Play Framework) to stream events efficiently to connected browser tabs without blocking server worker threads.
3. Scheduled Background Tasks:
   • Heartbeat & Ping: Pings connected clients every 5 seconds to detect ungraceful disconnects.
   • Presence Tracking: Emits join, leave, and timeout notices on presence(channel) channels.
   • Message Retention & Expiration: Periodically checks and purges expired retained messages (max 48 hours) and closes empty channels.
   • Delayed & Scheduled Queue: Holds delayed (_DELAY) and scheduled (_SCHEDULE) messages and dispatches them at the appointed second.