Yonexus/ARCHITECTURE.md

Yonexus — Architecture Overview

1. Purpose

Yonexus is a cross-instance communication system for OpenClaw.

The repository Yonexus is the umbrella/specification repository for the system. It contains:

• high-level planning
• architecture documents
• references to implementation repositories as git submodules

Yonexus is implemented as three repositories:

• Yonexus.Server — central hub plugin
• Yonexus.Client — client plugin
• Yonexus.Protocol — shared protocol specification, referenced as a submodule by both

---

2. Repository Roles

2.1 Yonexus (umbrella repo)

Purpose:

• system-level planning
• architecture documents
• cross-cutting decisions that apply to both server and client
• coordination of sub-repositories via git submodules

This repository should contain:

• top-level planning docs
• architecture overview
• feature checklists
• cross-cutting design rationale

It references:

• Yonexus.Server (submodule)
• Yonexus.Client (submodule)
• Yonexus.Protocol (submodule)

2.2 Yonexus.Protocol

Purpose:

• protocol specification (PROTOCOL.md)
• canonical JSON shape references
• shared type definitions (planned)

Referenced as a submodule by:

• Yonexus.Server/protocol
• Yonexus.Client/protocol

This is the single source of truth for the Yonexus protocol. Both server and client implementations must conform to the protocol defined here.

2.3 Yonexus.Server

Purpose:

• implementation of the central hub/server plugin
• server-side connection management
• server-side pairing/authentication/state tracking
• server-side dispatch and routing behavior

Contains:

• protocol/ — submodule pointing to Yonexus.Protocol
• PLAN.md
• implementation code

2.4 Yonexus.Client

Purpose:

• implementation of the client plugin
• outbound connection to Yonexus.Server
• local identity/keypair/secret management
• client-side pairing confirmation and authenticated reconnect
• client-side heartbeat and message sending

Contains:

• protocol/ — submodule pointing to Yonexus.Protocol
• PLAN.md
• implementation code

---

3. Repository Graph

Yonexus (umbrella)
├── Yonexus.Protocol  (submodule)
├── Yonexus.Server    (submodule)
│   └── protocol/     (nested submodule -> Yonexus.Protocol)
└── Yonexus.Client    (submodule)
    └── protocol/     (nested submodule -> Yonexus.Protocol)

Policy:

• protocol changes are always committed to Yonexus.Protocol first
• Yonexus.Server and Yonexus.Client update their protocol/ submodule ref after protocol version is stable
• umbrella Yonexus updates its submodule refs after server/client have stable versions

---

4. System Topology

A Yonexus deployment contains:

• exactly one Yonexus.Server instance
• one or more Yonexus.Client instances

Topology assumptions:

• Yonexus.Server runs on an OpenClaw instance reachable at a stable address
• each Yonexus.Client connects outbound to the server
• clients do not directly connect to each other in v1
• cross-client coordination is relayed through the server

Visual model:

Yonexus.Client A  --->
                     \
Yonexus.Client B  ---->  Yonexus.Server
                     /
Yonexus.Client C  --->

---

5. Shared vs Split Responsibilities

5.1 Yonexus.Protocol — Shared

These belong to the protocol repo and apply to both plugins:

• protocol format and message categories
• builtin message types and their semantics
• pairing security model
• nonce/timestamp validation rules
• heartbeat timing rules
• message rewrite rules
• reserved rule namespace (builtin)
• canonical JSON shapes
• naming and terminology

5.2 Server-Only Concerns (Yonexus.Server)

These belong in Yonexus.Server:

• WebSocket server startup
• listen host/port config
• client registry persistence
• public key / secret storage
• pairing code generation
• Discord DM notification to admin
• auth proof verification
• liveness status tracking
• client message rewriting and dispatch on server side
• sending messages to connected clients

5.3 Client-Only Concerns (Yonexus.Client)

These belong in Yonexus.Client:

• WebSocket client connection management
• reconnect/backoff logic
• local keypair generation
• local secret persistence
• pairing code submission
• auth proof construction/signing
• heartbeat sending
• sending messages to server
• receiving server messages and local dispatch

---

6. Communication Model

6.1 Transport

Transport is WebSocket.

• Yonexus.Server acts as server
• Yonexus.Client acts as client

6.2 Message Categories

Two message categories exist on the same transport:

Builtin protocol messages

Used for:

• hello/session setup
• pairing
• authentication
• heartbeat
• lifecycle/status
• protocol errors

Format:

builtin::{json}

Application rule messages

Used for higher-level cross-instance communication.

Format:

${rule_identifier}::${message_content}

Server rewrite rule:

When server receives a message from a client, before dispatch it rewrites:

${rule_identifier}::${sender_identifier}::${message_content}

---

7. Security Architecture

7.1 Pairing Model

Pairing is intentionally out-of-band.

When a new client needs pairing:

• server generates a pairing code
• server sends that code to a human administrator via Discord DM
• server does not send the code over the Yonexus WebSocket channel
• human relays the code to the client side manually
• client submits the code back to the server

This preserves a basic human-mediated trust step.

7.2 Post-Pairing Authentication

After pairing:

• server issues a shared secret
• client stores secret locally
• client already has a private key
• reconnect auth uses signed proof derived from:
  • secret
  • nonce
  • timestamp

7.3 Replay Protection

Server enforces:

• timestamp freshness (< 10s drift)
• nonce collision detection
• handshake rate threshold (>10 attempts in 10s is unsafe)
• re-pair requirement after unsafe conditions

---

8. State Ownership

8.1 Server-Owned State

Canonical server-owned state includes:

• allowed client identifiers
• trust state for each client
• client public key
• client secret
• pairing state
• pairing notification state
• recent nonce window
• recent handshake attempt window
• client liveness state

8.2 Client-Owned State

Canonical client-owned state includes:

• client identifier
• client private key
• client public key
• current shared secret
• last successful local trust metadata if needed

---

9. Plugin API Boundaries

9.1 Yonexus.Server API

Planned public API:

• sendMessageToClient(identifier, message)
• registerRule(rule, processor)

9.2 Yonexus.Client API

Planned public API:

• sendMessageToServer(message)
• registerRule(rule, processor)

The protocol defines semantics; implementation details belong in each submodule.

---

10. Documentation Ownership

10.1 Umbrella Repo Docs

Should contain:

• system architecture
• cross-cutting feature list
• global design rationale
• cross-repo coordination notes

10.2 Protocol Repo Docs

Must contain:

• protocol specification (PROTOCOL.md)
• canonical message shapes
• protocol versioning notes

10.3 Server Repo Docs

Should contain:

• server setup
• server config reference
• server persistence model
• server operational behavior
• implementation tasks

10.4 Client Repo Docs

Should contain:

• client setup
• client config reference
• client local storage model
• client reconnect/heartbeat behavior
• implementation tasks

---

11. Development Flow

Recommended flow:

1. define cross-cutting behavior in Yonexus umbrella
2. finalize protocol in Yonexus.Protocol
3. update submodule refs in Yonexus.Server and Yonexus.Client
4. implement server-side protocol handling in Yonexus.Server
5. implement client-side protocol handling in Yonexus.Client
6. keep protocol changes synchronized back into umbrella docs

---

12. Non-Goals of the Umbrella Repo

The umbrella repo should avoid becoming:

• the place where all implementation code lives
• a dumping ground for server-only or client-only details
• a duplicate of submodule READMEs without system-level value

Its job is coordination, not code concentration.