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

```text
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:

```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}
```

---

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