nav/Yonexus
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
95dc06453a75a45f2a1eb73dda8ecc750572a353
Yonexus/ARCHITECTURE.md
nav 95dc06453a add architecture overview
2026-04-01 01:08:44 +00:00

7.0 KiB
Raw Blame History

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.

Reference in New Issue View Git Blame Copy Permalink