From 95dc06453a75a45f2a1eb73dda8ecc750572a353 Mon Sep 17 00:00:00 2001 From: nav Date: Wed, 1 Apr 2026 01:08:44 +0000 Subject: [PATCH] add architecture overview --- ARCHITECTURE.md | 319 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 319 insertions(+) create mode 100644 ARCHITECTURE.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..4b5d32b --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,319 @@ +# 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.