Data & Messaging

Storage Design

CF Messenger avoids traditional SQL databases in favour of low-latency edge primitives:

• SESSION_KV: 20-minute TTL tokens, presence heartbeats, and bot rotation metrics. Globally replicated for rapid socket revalidation.
• Durable Objects (ChatRoom, PresenceRoom): Handle broadcast logic, schema enforcement (Zod), and rate limiting with in-memory buffers.
• Hibernation Mirror: When a Durable Object hibernates, the latest buffer is mirrored to KV for rapid bootstrapping.

Data Model

Entity	Storage	Key Attributes
User	Seeded list	ID, persona, avatar, archetype hints
Session	SESSION_KV	SessionID, UserID, expiry, nonce, location hint (uk)
Message	DO memory	ID, RoomID, Sender, Type, Timestamp, Content
Presence	SESSION_KV + DO	Status flag, last heartbeat, routing hint

---

WebSocket Protocol

Every payload is JSON-formatted and validated via Zod.

Primary Message Types

• chat: Text ≤ 2048 characters.
• nudge: Screen shake/alert limited to 3 per 10s.
• wink: Flash-style animated notifications keyed by winkId.
• typing: TTL-bound typing indicator (3 seconds).
• presence: Online/busy/away updates pushed to the PresenceRoom.

Handlers & Constraints

• NudgeHandler: Rate-limited per user (3 per 10s).
• TypingHandler: Emits a forced typing:false after TTL to clear stale UI indicators.
• WinkHandler: Combines timestamps and winkId hashes to synchronise playback across clients.

---

Standard Edge API Spec (v1.0)

This section defines the unified API structure for applications on the *.cfdemo.link zone.

Request/Response Envelope

All endpoints MUST use a consistent JSON structure to facilitate automated parsing:

type ApiResponse<T> = {
  success: boolean;
  data?: T;
  error?: { code: string; message: string };
  meta: { timestamp: number; requestId: string };
};

Endpoint Hierarchy

Endpoint Root	Method	Use Case	Primary Storage
/api/auth/login	POST	Turnstile-gated session creation	KV
/api/auth/me	GET	Session validation/Profile fetch	KV/D1
/api/data/:collection	GET/POST	Relational CRUD (Orders, Users)	D1
/api/ws/room/:id	GET (Upgrade)	Real-time synchronisation	Durable Object
/api/ws/presence	GET (Upgrade)	Global presence tracking	Durable Object