# 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:

```text
builtin::{json}
```

### Application rule messages
Used for higher-level cross-instance communication.

Format:

```text
${rule_identifier}::${message_content}
```

Server rewrite rule:

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

```text
${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.