.

sync-server/README.md

@@ -1,9 +1,29 @@
 # Sync server
 
+## Code layout
 
-- ban using unwraps
+HTTP handlers live in `src/server/endpoints/`. Content and manifest writes check
+for an already accepted request, validate the parent version, write the new event
+and data in one transaction, then commit before notifying connected clients.
+`endpoints/utils.rs` shares request fingerprinting, replay checks, and commit/notify
+ordering. Infrastructure errors convert to `SyncServerError`; validation chooses
+client, authentication, or missing-resource errors explicitly.
 
-## API v5
+`app_state/database.rs` manages per-vault connection pools. Its `queries`,
+`mutations`, and `history` modules own data reads, writes, and history checkpoints.
+`StoredDocumentVersion` describes database rows; the API response models remain
+separate. `utils/portable_path.rs` validates individual filenames and the manifest's
+file/directory relationships.
+
+The WebSocket endpoint authenticates once, registers a cursor session, and forwards
+updates through `AuthenticatedConnection`. It separates durable-history checks,
+client-message handling, and cursor filtering, and always removes the registered
+session on exit. `app_state/cursors.rs` retains and expires cursor presence.
+
+Run `cargo fmt --check`, `cargo clippy --all-targets`, and `cargo test` in this
+package. The Rust protocol models generate the client's `services/types/` files.
+
+## API v4
 
 The server is a compare-and-swap store. Content versions do not contain paths or
 deletions. A separately versioned file manifest owns the namespace and membership.
@@ -20,7 +40,7 @@ All routes below are under `/vaults/:vault_id` and require bearer authentication
 | `PUT /file-manifest`                                       | CAS the complete file manifest.                                                         |
 | `GET /vault-snapshot`                                      | File manifest, referenced content heads, and event watermark from one read transaction. |
 | `GET /events-since?after=N`                                | Every event after N, in order, with the current watermark.                              |
-| `GET /ws`                                                  | Ordered event delivery and ephemeral cursor positions.                                  |
+| `GET /ws`                                                  | Vault-change hints and ephemeral cursor positions.                                  |
 
 A content push includes a `Device-Id` header and this JSON body: