# WebSocket Protocol

This document describes the WebSocket events used for real-time collaborative graph editing.

## Connection

- **Endpoint:** `/ws`
- **Protocol:** WebSocket (ws:// or wss://)

On connection, the server immediately sends a `fullSync` event with the current graph state.

---

## Event Types

### Client Request Events

These events are sent from the client to the server.

#### `addNode`

Request to add a new node to the graph.

```json
{
  "type": "addNode",
  "node": {
    "x": 1.5,
    "y": 2.0,
    "z": -1.0
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `node.x` | float | X coordinate |
| `node.y` | float | Y coordinate |
| `node.z` | float | Z coordinate |

**Server behavior:** Assigns a unique ID to the node, adds it to the graph, and broadcasts the confirmed node to all clients.

---

#### `addEdge`

Request to add an edge between two existing nodes.

```json
{
  "type": "addEdge",
  "edge": {
    "from": 0,
    "to": 3
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `edge.from` | int | Source node ID |
| `edge.to` | int | Target node ID |

**Server behavior:** Validates that both nodes exist, the edge doesn't already exist, and nodes aren't the same. If valid, adds the edge and broadcasts to all clients. Invalid requests are silently ignored.

---

#### `reset`

Request to clear the graph and restore initial state.

```json
{
  "type": "reset"
}
```

**Server behavior:** Clears all nodes and edges, then broadcasts a `fullSync` with an empty graph to all clients.

---

### Server Publish Events

These events are sent from the server to clients.

#### `fullSync`

Full graph state synchronization. Sent on initial connection and after reset.

```json
{
  "type": "fullSync",
  "graph": {
    "nodes": [
      {"id": 0, "x": 0, "y": 0, "z": 0},
      {"id": 1, "x": 3, "y": 2, "z": 1}
    ],
    "edges": [
      {"from": 0, "to": 1}
    ]
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `graph.nodes` | array | All nodes in the graph |
| `graph.nodes[].id` | int | Unique node identifier |
| `graph.nodes[].x` | float | X coordinate |
| `graph.nodes[].y` | float | Y coordinate |
| `graph.nodes[].z` | float | Z coordinate |
| `graph.edges` | array | All edges in the graph |
| `graph.edges[].from` | int | Source node ID |
| `graph.edges[].to` | int | Target node ID |

**Client behavior:** Replace entire local graph state with server state. Rebuild visualization.

---

#### `addNode`

Broadcast when a node has been added (by any client).

```json
{
  "type": "addNode",
  "node": {
    "id": 6,
    "x": 1.5,
    "y": 2.0,
    "z": -1.0
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `node.id` | int | Server-assigned unique ID |
| `node.x` | float | X coordinate |
| `node.y` | float | Y coordinate |
| `node.z` | float | Z coordinate |

**Client behavior:** Add the node to local graph and create visual representation.

---

#### `addEdge`

Broadcast when an edge has been added (by any client).

```json
{
  "type": "addEdge",
  "edge": {
    "from": 0,
    "to": 6
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `edge.from` | int | Source node ID |
| `edge.to` | int | Target node ID |

**Client behavior:** Add the edge to local graph and create visual representation.

---

## Message Flow

```
Client A                    Server                    Client B
    |                          |                          |
    |-------- connect -------->|                          |
    |<------ fullSync ---------|                          |
    |                          |                          |
    |-------- addNode -------->|                          |
    |                          |--- (validate & assign ID)
    |<------ addNode ----------|-------- addNode -------->|
    |                          |                          |
    |                          |<------- addEdge ---------|
    |                          |--- (validate)            |
    |<------ addEdge ----------|-------- addEdge -------->|
    |                          |                          |
```

## Error Handling

- Invalid operations (bad node IDs, duplicate edges, self-loops) are silently ignored
- The server never sends error messages; invalid requests simply produce no broadcast
- Clients should not assume their request succeeded until they receive the broadcast