# Yonexus.Server — Scaffold Plan

This document refines the repository structure into concrete planned files and responsibilities.

## 1. Planned Tree

```text
.
├── plugin/
│   ├── core/
│   │   ├── registry.ts
│   │   ├── pairing.ts
│   │   ├── auth.ts
│   │   ├── heartbeat.ts
│   │   ├── dispatch.ts
│   │   └── errors.ts
│   ├── hooks/
│   │   ├── onGatewayStart.ts
│   │   └── onGatewayStop.ts
│   ├── commands/
│   │   ├── listClients.ts
│   │   ├── showClient.ts
│   │   └── rePairClient.ts
│   ├── tools/
│   │   ├── sendMessageToClient.ts
│   │   ├── listClientStatus.ts
│   │   └── getPairingState.ts
│   ├── index.ts
│   └── openclaw.plugin.json
├── skills/
│   └── ...
├── servers/
│   ├── wsServer.ts
│   └── sessionManager.ts
├── scripts/
│   └── install.mjs
├── protocol/
│   └── ... (submodule)
├── PLAN.md
├── STRUCTURE.md
└── SCAFFOLD.md
```

This is a planning scaffold, not yet an implementation commitment down to exact filenames. Names may evolve, but responsibilities should remain stable.

---

## 2. `plugin/index.ts`

`plugin/index.ts` is wiring only.

Planned responsibilities:
- import server core modules
- import hooks
- import commands
- import tools
- initialize server runtime container
- register hooks with OpenClaw
- register commands with OpenClaw
- register tools with OpenClaw

Design rule:
- no pairing/auth/dispatch business logic should live directly in this file

---

## 3. `plugin/openclaw.plugin.json`

Planned manifest responsibilities:
- define plugin name: `Yonexus.Server`
- define entrypoint
- declare version
- define config schema / default config shape
- declare plugin metadata
- declare permissions if needed

### Planned Config Shape

```json
{
  "followerIdentifiers": [],
  "notifyBotToken": "",
  "adminUserId": "",
  "listenHost": "0.0.0.0",
  "listenPort": 8787,
  "publicWsUrl": ""
}
```

### Planned Validation Expectations

- `listenPort` must be required
- `followerIdentifiers` must be an array
- `notifyBotToken` must be required
- `adminUserId` must be required

---

## 4. `plugin/core/`

### `registry.ts`
Planned responsibilities:
- client registry CRUD
- active session tracking
- persistent state load/save

### `pairing.ts`
Planned responsibilities:
- pairing code generation
- pairing pending state
- Discord DM notification orchestration
- pair_confirm validation
- secret issuance

### `auth.ts`
Planned responsibilities:
- auth_request verification
- signature verification
- nonce window validation
- rate-limit checks
- re-pair trigger decisions

### `heartbeat.ts`
Planned responsibilities:
- lastHeartbeatAt updates
- status transitions
- sweep timer logic
- disconnect timeout handling

### `dispatch.ts`
Planned responsibilities:
- builtin message routing
- application rule rewriting
- rule registry
- rule dispatch
- sendMessageToClient routing

### `errors.ts`
Planned responsibilities:
- typed/structured error definitions
- standard server-side error codes

---

## 5. `plugin/hooks/`

### `onGatewayStart.ts`
Planned responsibilities:
- initialize registry/runtime
- start WebSocket server
- start heartbeat sweep

### `onGatewayStop.ts`
Planned responsibilities:
- stop heartbeat sweep
- close sockets gracefully
- persist final state if needed

---

## 6. `plugin/commands/`

These are optional in early versions, but the directory should exist.

Potential first commands:
- `listClients.ts` — list known clients and statuses
- `showClient.ts` — inspect one client’s trust/liveness state
- `rePairClient.ts` — revoke trust and force next reconnect to re-pair

---

## 7. `plugin/tools/`

Potential first tools:
- `sendMessageToClient.ts`
- `listClientStatus.ts`
- `getPairingState.ts`

These should wrap core logic, not duplicate it.

---

## 8. `servers/`

### `wsServer.ts`
Planned responsibilities:
- WebSocket server startup and bind
- connection accept lifecycle
- socket-level send/receive plumbing

### `sessionManager.ts`
Planned responsibilities:
- map identifiers to active connections
- enforce one active session per identifier
- close/replace older sessions when needed

Design rule:
- service bootstrap/network transport code belongs here
- reusable business/state logic stays in `plugin/core/`

---

## 9. `skills/`

Initial version may keep this minimal.

Possible future skill topics:
- Yonexus.Server operations
- pairing recovery
- debugging auth failures

---

## 10. `scripts/install.mjs`

Planned CLI responsibilities:
- `--install`
- `--uninstall`
- `--openclaw-profile-path <path>`

Planned install behavior:
- build output copied into the OpenClaw plugin directory
- install target path determined by profile path

Planned uninstall behavior:
- remove installed plugin directory
- optionally clean server plugin config if explicitly desired later

---

## 11. Initial Bring-Up Order

Recommended first implementation order:
1. manifest + `plugin/index.ts`
2. `servers/wsServer.ts`
3. `plugin/core/registry.ts`
4. hello / hello_ack routing
5. pairing flow
6. auth flow
7. heartbeat
8. commands/tools

---

## 12. Notes

- `protocol/` is the single protocol source of truth; do not duplicate protocol docs in this repo.
- File names can change, but the wiring/core/service separation should remain.
- Commands and tools can start thin and grow later.