nav/Yonexus
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

add Yonexus.Protocol submodule and update architecture docs

Browse Source
This commit is contained in:
nav
2026-04-01 01:21:47 +00:00
parent 95dc06453a
commit 64dac56e37
6 changed files with 160 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

178
ARCHITECTURE.md
View File

@@ -6,13 +6,13 @@ 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
- architecture documents
- references to implementation repositories as git submodules
Yonexus is implemented as two separate plugins:
- `Yonexus.Server`
- `Yonexus.Client`
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
---
@@ -23,20 +23,34 @@ Yonexus is implemented as two separate plugins:
Purpose:
- system-level planning
- architecture documents
- protocol definition
- shared design decisions
- cross-repo coordination
- 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
- protocol docs
- feature checklists
- architecture overview
- cross-cutting decisions that apply to both server and client
- feature checklists
- cross-cutting design rationale
This repository should **not** become the place where all implementation code lives.
It references:
- `Yonexus.Server` (submodule)
- `Yonexus.Client` (submodule)
- `Yonexus.Protocol` (submodule)
## 2.2 `Yonexus.Server`
## 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
@@ -44,7 +58,12 @@ Purpose:
- server-side pairing/authentication/state tracking
- server-side dispatch and routing behavior
## 2.3 `Yonexus.Client`
Contains:
- `protocol/` — submodule pointing to `Yonexus.Protocol`
- `PLAN.md`
- implementation code
## 2.4 `Yonexus.Client`
Purpose:
- implementation of the client plugin
@@ -53,9 +72,32 @@ Purpose:
- 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. System Topology
## 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
@@ -69,7 +111,7 @@ Topology assumptions:
Visual model:
```text
```
Yonexus.Client A --->
\
Yonexus.Client B ----> Yonexus.Server
@@ -79,29 +121,24 @@ Yonexus.Client C --->
---
## 4. Shared vs Split Responsibilities
## 5. Shared vs Split Responsibilities
## 4.1 Shared System Concerns
## 5.1 Yonexus.Protocol — Shared
These belong to the umbrella repo and apply to both plugins:
- protocol format
- builtin message types
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
These should live primarily in:
- `PLAN.md`
- `PROTOCOL.md`
- `FEAT.md`
- `ARCHITECTURE.md`
## 5.2 Server-Only Concerns (Yonexus.Server)
## 4.2 Server-Only Concerns
These belong in `Yonexus.Server` planning/implementation:
These belong in `Yonexus.Server`:
- WebSocket server startup
- listen host/port config
- client registry persistence
@@ -113,9 +150,9 @@ These belong in `Yonexus.Server` planning/implementation:
- client message rewriting and dispatch on server side
- sending messages to connected clients
## 4.3 Client-Only Concerns
## 5.3 Client-Only Concerns (Yonexus.Client)
These belong in `Yonexus.Client` planning/implementation:
These belong in `Yonexus.Client`:
- WebSocket client connection management
- reconnect/backoff logic
- local keypair generation
@@ -128,16 +165,16 @@ These belong in `Yonexus.Client` planning/implementation:
---
## 5. Communication Model
## 6. Communication Model
## 5.1 Transport
## 6.1 Transport
Transport is WebSocket.
- `Yonexus.Server` acts as server
- `Yonexus.Client` acts as client
## 5.2 Message Categories
## 6.2 Message Categories
Two message categories exist on the same transport:
@@ -175,9 +212,9 @@ ${rule_identifier}::${sender_identifier}::${message_content}
---
## 6. Security Architecture
## 7. Security Architecture
## 6.1 Pairing Model
## 7.1 Pairing Model
Pairing is intentionally out-of-band.
@@ -190,7 +227,7 @@ When a new client needs pairing:
This preserves a basic human-mediated trust step.
## 6.2 Post-Pairing Authentication
## 7.2 Post-Pairing Authentication
After pairing:
- server issues a shared secret
@@ -201,7 +238,7 @@ After pairing:
- nonce
- timestamp
## 6.3 Replay Protection
## 7.3 Replay Protection
Server enforces:
- timestamp freshness (`< 10s` drift)
@@ -211,9 +248,9 @@ Server enforces:
---
## 7. State Ownership
## 8. State Ownership
## 7.1 Server-Owned State
## 8.1 Server-Owned State
Canonical server-owned state includes:
- allowed client identifiers
@@ -226,7 +263,7 @@ Canonical server-owned state includes:
- recent handshake attempt window
- client liveness state
## 7.2 Client-Owned State
## 8.2 Client-Owned State
Canonical client-owned state includes:
- client identifier
@@ -237,83 +274,78 @@ Canonical client-owned state includes:
---
## 8. Plugin API Boundaries
## 9. Plugin API Boundaries
## 8.1 Yonexus.Server API
## 9.1 Yonexus.Server API
Planned public API:
- `sendMessageToClient(identifier, message)`
- `registerRule(rule, processor)`
## 8.2 Yonexus.Client API
## 9.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.
The protocol defines semantics; implementation details belong in each submodule.
---
## 9. Documentation Ownership
## 10. Documentation Ownership
## 9.1 Umbrella Repo Docs
## 10.1 Umbrella Repo Docs
Should contain:
- system architecture
- protocol spec
- cross-cutting feature list
- global design rationale
- cross-repo coordination notes
## 9.2 Server Repo Docs
## 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
- server implementation tasks
- implementation tasks
## 9.3 Client Repo Docs
## 10.4 Client Repo Docs
Should contain:
- client setup
- client config reference
- client local storage model
- client reconnect/heartbeat behavior
- client implementation tasks
- implementation tasks
---
## 10. Development Flow
## 11. 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
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 only place where implementation changes happen
- a dumping ground for server-only details
- a dumping ground for client-only details
- 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.