# Technical Architecture Tradeoff Brief
## 1. Problem Statement & Technical Goal
*Why is this technical decision required? What performance or scale demands exist?*
Web Sockets vs. Polling
Web Sockets provide true bidirectional, sub-second latency with minimal overhead, making them essential for chat, collaborative editing, or live trading. However, they introduce high infrastructure complexity, requiring sticky sessions, shared state (e.g., Redis), and manual reconnection logic, while consuming 10–50 KB of memory per idle connection. They are best reserved for scenarios requiring under-1-second updates or continuous two-way communication.
Polling (including short or long polling) offers stateless scalability and universal compatibility with minimal implementation effort, but introduces latency equal to the polling interval and high API quota costs. It is suitable only when staleness over 30 seconds is acceptable or when corporate proxies block WebSocket upgrades. For server-to-client only updates, Server-Sent Events (SSE) are a superior middle ground, offering built-in reconnection and lower complexity than Web Sockets.
The decision hinges on one question: does the product need bidirectional communication at high cadence, or is it predominantly server-push with occasional client mutations? If the latter (which is the case for most SaaS sync use cases), SSE + REST in-house is the lowest-risk, lowest-cost path that still meets sub-second latency.
REST vs. Graph QL for Data Fetching
REST remains the standard for simple CRUD operations and public APIs due to its native HTTP caching and predictability. However, it suffers from over-fetching and under-fetching, requiring multiple round-trips for complex views and lacking native real-time capabilities (requiring polling or external Web Sockets).
Graph QL eliminates over-fetching by allowing clients to request exactly the data needed in a single query, making it ideal for multiple client types with varying data shapes. Its trade-offs include complex query governance, potential N+1 resolver performance issues, and difficult caching. For real-time needs, Graph QL supports subscriptions (often over Web Sockets), but this adds protocol complexity compared to simple SSE endpoints.
Build In-House vs. Third-Party Integration
Third-Party APIs (using Webhooks or Polling) are generally superior for integrating with established platforms (e.g., Stripe, GitHub, CRMs). Webhooks provide instant delivery with near-zero API quota costs on the client side, though they require handling duplicate deliveries (idempotency) and signature verification. Polling is safer for systems with fragile or absent webhook support (e.g., older ERP systems), trading off latency for reliability.
Building in-house real-time infrastructure is justified only when data sensitivity or ultra-low latency requirements cannot be met by third-party providers. It requires significant investment in connection management, scaling, and debugging. For most SaaS products, starting with third-party webhooks or SSE allows for faster iteration, with Web Sockets adopted later only when usage data proves the need for bidirectional control.
## 2. Option Comparison Matrix
| Feature | REST | Graph QL | Web Sockets | SSE | Polling |
| Best For |Standard CRUD | Flexible data | Bidirectional | Unidirectional | Infrequent Updates |
| Latency | High | High | Lowest | Low | High |
| Complexity | Low | Moderate | High | Low | Low |
| Scaling | Easy (Stateless)| Moderate | Hard | Moderate | Easy |
| Direction | Client → Server | Client → Server| Bidirectional| Server → Client | Client → Server |
Recommendation: Use REST for general data access, Graph QL if clients require flexible data shapes, and SSE for simple real-time feeds. Reserve Web Sockets for true bidirectional, sub-second requirements. For external integrations, prefer Webhooks with reconciliation logic unless the provider lacks reliable webhook support.
## 3. Data Flow & API Schema Overview
Data Model & Payload Overview
Entity Hierarchy
Sync State
├── cursor: string (opaque, monotonic)
├── entities: Entity[]
└── meta: { version, timestamp, etag }
Entity
├── id: UUID v7
├── type: "order" | "user" | "inventory" | ...
├── data: object (type-specific)
├── version: int (optimistic concurrency)
├── updatedAt: ISO-8601
└── deleted: bool (tombstone)
SyncEvent (SSE/WS envelope)
├── id: "evt_{nanosecond}"
├── type: "entity.created" | "entity.updated" | "entity.deleted" | "presence" | "ping"
├── channel: string
├── payload: Entity | Presence Payload
├── seq: int (per-channel monotonic)
└── timestamp: epoch_ms
```
## 4. Failure Modes & Resilience
The failure-mode design rests on four pillars: rate limiting is handled server-side via X-RateLimit-* headers and Retry-After on 429s, while the client pre-throttles with a token bucket and retries with exponential backoff + jitter, capping at 60s and falling back to an offline queue after 5 failures. Database locks are mitigated through optimistic concurrency (version field → 409 on mismatch), lock ordering, a 5s lock timeout, and server-side deadlock retries with jitter; the client re-reads and re-applies up to 3 times before surfacing a merge UI. API downtime is absorbed by a per-endpoint circuit breaker (5 failures → OPEN → 30s → HALF_OPEN probe), while the client persists mutations to a local offline queue and flushes them FIFO at 10 req/s on reconnect, handling 409s and expired cursors inline. Fallback follows a degradation ladder — WebSocket → SSE → short polling (5s) → long polling (30s) → full resync → offline mode with local cache — with each step triggered by repeated failures at the current layer, and recovery re-escalates the chain after a successful probe.
## 5. Recommendation & Engineering Alignment
Recommendation
Ship SSE as the default transport. Add WebSocket only behind a feature flag for the specific bidirectional use cases (presence, collaborative cursors) that actually require it.
Justification:
95% of your sync traffic is server→client (entity updates, status changes, notifications). SSE handles this with ~10 lines of server code vs. 50+ for WebSocket, built-in reconnection via Last-Event-ID, and zero sticky-session or pub/sub backplane requirements at first scale.
Operational risk is asymmetric. A WebSocket misconfiguration (proxy timeout, load balancer idle close, memory leak on idle connections) is a P1 incident. An SSE misconfiguration degrades gracefully to polling. Your team can debug SSE with curl; WebSocket requires a client.
The degradation ladder already covers the gap. If SSE fails 5×, the client falls back to 5s polling. You never go dark. WebSocket adds a layer to that ladder without changing the failure-mode surface.
WebSocket earns its complexity only when the client must send at the same cadence it receives (collaborative editing, multiplayer, live trading). If that's not in the near-term roadmap, it's premature infrastructure.
REST for mutations (not GraphQL) keeps the API surface small, cacheable, and auditable. GraphQL's N+1 resolver risk and caching difficulty are not worth it for a sync API with a fixed entity set.
Build in-house, not third-party. Your data model is product-specific, latency requirements are moderate (sub-second, not sub-100ms), and a third-party (Ably, PubNub, Socket.io Cloud) would add per-connection cost at scale without buying capability you can't build in ~2 sprints.
The mitigation plan unfolds in five phases: Sprint 1–2 ships the core REST + SSE stack with no WebSocket; Sprint 3–4 hardens it with circuit breakers, offline queues, Redis replay, and load-testing to 10k concurrent connections; Sprint 5–6 (gated behind a feature flag) adds WebSocket solely for presence/collaborative cursors, with SSE remaining the primary transport; Sprint 7 adds full observability dashboards and alerting on all seven key metrics. Quarterly architecture reviews then decide whether WebSocket is earning its operational cost and whether any degradation-ladder layer is dead weight. Ongoing rules enforce that no new transport is added without a usage metric, refactors happen in vertical slices (never alongside new feature work), debt is tracked explicitly in a TECH_DEBT.md, and a kill-switch feature flag can auto-degrade all clients to polling if SSE reconnect rate spikes — no deploy required.