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
• protocol specification
• shared architectural decisions
• references to implementation repositories as git submodules

Yonexus is implemented as two separate plugins:

• Yonexus.Server
• Yonexus.Client

---

2. Repository Roles

2.1 Yonexus (umbrella repo)

Purpose:

• system-level planning
• architecture documents
• protocol definition
• shared design decisions
• cross-repo coordination

This repository should contain:

• top-level planning docs
• protocol docs
• feature checklists
• architecture overview
• cross-cutting decisions that apply to both server and client

This repository should not become the place where all implementation code lives.

2.2 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

2.3 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

---

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

---

4. Shared vs Split Responsibilities

4.1 Shared System Concerns

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

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

These should live primarily in:

• PLAN.md
• PROTOCOL.md
• FEAT.md
• ARCHITECTURE.md

4.2 Server-Only Concerns

These belong in Yonexus.Server planning/implementation:

• 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

4.3 Client-Only Concerns

These belong in Yonexus.Client planning/implementation:

• 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

---

5. Communication Model

5.1 Transport

Transport is WebSocket.

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

5.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}

---

6. Security Architecture

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

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

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

---

7. State Ownership

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

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

---

8. Plugin API Boundaries

8.1 Yonexus.Server API

Planned public API:

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

8.2 Yonexus.Client API

Planned public API:

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

The umbrella repo should define the semantics of these APIs, but implementation details belong in each submodule.

---

9. Documentation Ownership

9.1 Umbrella Repo Docs

Should contain:

• system architecture
• protocol spec
• cross-cutting feature list
• global design rationale

9.2 Server Repo Docs

Should contain:

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

9.3 Client Repo Docs

Should contain:

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

---

10. Development Flow

Recommended flow:

1. define cross-cutting behavior in Yonexus
2. split actionable work into Yonexus.Server and Yonexus.Client
3. implement server-side protocol handling in Yonexus.Server
4. implement client-side protocol handling in Yonexus.Client
5. keep protocol changes synchronized back into umbrella docs

---

11. Immediate Next Documents

After this architecture file, the next documents to maintain are:

• Yonexus.Server/PLAN.md
• Yonexus.Client/PLAN.md
• optionally later:
  • Yonexus.Server/README.md
  • Yonexus.Client/README.md
  • server/client task breakdown docs

---

12. Non-Goals of the Umbrella Repo

The umbrella repo should avoid becoming:

• the only place where implementation changes happen
• a dumping ground for server-only details
• a dumping ground for client-only details
• a duplicate of submodule READMEs without system-level value

Its job is coordination, not code concentration.