add architecture overview

2026-04-01 01:08:44 +00:00
parent eb7a6248f8
commit 95dc06453a
1 changed files with 319 additions and 0 deletions
--- a/ARCHITECTURE.md
+++ 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.