SITE-31 — Server Decision Record (ADR)

Status: PROPOSED — transport/server unbuilt; client seams implemented and tested Date: 2026-09-27 Decides: which server the site app syncs against, what authority it has per data class, and what the client may assume before it exists.

1. Decision

Extend the tracked nimanyatta/ tree (pinned sibling commit 84fe56de61ee39f464a18f4aa575307a2966d3b6, see nigig-site-core/src/interop.rs::SERVER_PIN_COMMIT) into the scope §5 backend: Rust API service + PostgreSQL + S3-compatible object storage, with delta sync, resumable media upload, server arbitration for shared-document conflicts, and organisation backup/export.

2. Why this server and not another

The tree is already in this repository, with an auth model, a database layer, broadcast/realtime paths, and REST coverage repaired in-branch.
Its WebSocket chat protocol (nimanyatta/crates/nimanyatta-protocol, postcard) is a workspace member here and its wire format is pinned by characterization tests — the only app/server surface with that property.
Its HTTP sync DTOs (SyncRequest/SyncResponse/timelines) are readable in-tree via nigig-lite/crates/common; the field-level contract (body, externally-tagged Message) is verified by the extracted harness, not assumed.

3. Per-data-class authority (the E2EE divergence, resolved)

Scope §6 demands server-side authority for approvals, signatures, locking and roles; SITE-08/09 demand end-to-end protection where the server must not read payloads. Both hold, on different data:

Data class	Authority	Rationale
Approvals, signatures, locks, roles, membership	Server-arbitrated. Server enforces, both sides check.	Tamper-evidence requires a party both endpoints can blame.
Report/worker/PII application payloads in transit	E2EE where reviewed (`e2ee` envelopes); otherwise local-only.	Server sees routing metadata + ciphertext lengths only.
Chat transport until E2EE review passes	Absent. Local cache + offline outbox only.	No TLS-only/plain-room substitute ships (SITE-P0-05).
Conflicts on shared documents	Server arbitration; loser flagged for the Report Master.	Deterministic order beats wall-clock voting.

4. Explicit non-decisions (still open, owned elsewhere)

Hosting model and data residency (scope §18 Q1): option per organisation; no default asserted here.
AI/STT provider and budget (scope §18 Q3): no provider named; no audio leaves a device without recorded consent regardless of provider.
Workspace membership of nimanyatta/nigig-common: both carry deliberate independent [workspace] tables; absorbing them is the server team's decision, not a mechanical change. Until then the client pins by file-level drift detection (interop::assert_pinned_tree), never by importing the server workspace.
Client portal timing (scope §18 Q5): digest-by-share first (R4), portal after this server exists (R5).

5. Consequences for the client

integrations.rs intents (share, calendar, webhooks, API scopes, backup manifest, remote lookup) are validated locally and dispatched nowhere: every dispatch names its missing provider. No caller can mistake validation for delivery.
Webhook/API traffic authenticates against the SITE-20 capability matrix on both ends; the server enforces it independently.
Backup/restore drills run against this server once it serves the API; until then the local encrypted operation journal is the durability story and no sync claim ships.

6. Reconnect discipline (thundering-herd defense)

A server restart that drops 100,000 WebSocket clients must not be answered by 100,000 immediate reconnects — that is a self-inflicted traffic attack, and "reconnect immediately" in any client is a bug.

Client rules (implemented and tested in net_client::RetryPolicy):

Every retry waits an exponential backoff (500 ms base, 30 s cap, 8-attempt budget) with deterministic equal jitter, so a fleet that failed together does not retry together. No RNG dependency: the spread derives from the operation id, exact in tests.
A server Retry-After always wins within the cap; a missing or absurd value can neither park a client forever nor be ignored.
Bulk replays drain paced: journal catch-up and outbox flush go out in SYNC_DRAIN_BATCH-sized batches (chat::drain_outbox_paced), spaced by the retry policy — never as one burst per reconnect.
Reconnect reuses the existing session/token; it never re-runs login or re-fetches full state first (no AUTH stampede, no thundering snapshot).

Server expectations (specified here, owned by the server team):

Refuse new upgrades while warming, with Retry-After, instead of accepting connections that cannot be served yet (readiness gate).
Shed gracefully past capacity: bound connection count, evict oldest-idle first, and say so in metrics — never accept-then-blackhole.
Recover staggered: per-device sequence resumption (already in the envelope design) rather than mass snapshot pushes.
Load-test scenario to add once the server harness runs here: drop N clients simultaneously, assert p99 reconnect delay spread covers the backoff window, AUTH rate stays flat, and no client retries before its computed delay.

5.3 KiB Raw Permalink Blame History