useEffect(() => {
  fetch('/api/data').then(r => r.json()).then(setData);
}, []);

User intent
  -> UI boundary
  -> route/query/form/server-function boundary
  -> typed request
  -> browser policy
  -> transport
  -> API contract
  -> response/error contract
  -> parsing/validation
  -> cache/update/invalidation
  -> rendering state
  -> telemetry
  -> recovery path

['cases']

['tenant', tenantId, 'cases', 'list', { status, ownerId, page, sort, locale }]

remote
shared
async
cacheable
stale-able
invalidatable
permission-sensitive

local
immediate
usually private to UI interaction
owned by the browser session/component

My replica may no longer represent the server truth.

throw new Error('Something went wrong');

route -> user -> permissions -> dashboard -> widgets -> each widget details

# Client-Server Communication Review

## Screen / Feature
- Name:
- Route:
- Owner:
- User roles:
- Tenant scope:

## Remote Data
| Data | Owner | Query Key | Freshness | Cache Scope | Sensitive? |
|---|---|---|---|---|---|
| | | | | | |

## Mutations
| Command | Endpoint / Action | Idempotent? | Affected Queries | Conflict Policy | Audit Event |
|---|---|---:|---|---|---|
| | | | | | |

## Failure States
| Failure | UI Behavior | Retry? | Recovery |
|---|---|---:|---|
| 401 | | | |
| 403 | | | |
| 409/412 | | | |
| 429 | | | |
| timeout | | | |
| malformed response | | | |

## Performance
- Critical route data:
- Deferred data:
- Waterfall depth:
- Expected request count:
- Largest response:
- Prefetch policy:
- Cache headers:

## Security / Privacy
- PII fields returned:
- Fields hidden by UI but still transported:
- Signed URL usage:
- Persisted cache:
- Telemetry redaction:
- Tenant/user isolation:

## Observability
- Operation names:
- Request IDs:
- Trace propagation:
- Client metrics:
- Server metrics:
- Dashboards:

## Testing
- MSW handlers:
- Contract tests:
- Race tests:
- Offline tests:
- Permission tests:
- Cache invalidation tests:

[ ] URL is canonical and stable.
[ ] Query params are encoded through a serializer, not string concatenation.
[ ] Method semantics are correct.
[ ] Headers are explicit and minimal.
[ ] Credentials mode is intentional.
[ ] AbortSignal is passed through.
[ ] Timeout/deadline policy exists where needed.
[ ] Idempotency key exists for retry-sensitive mutation.

[ ] HTTP errors are handled separately from network errors.
[ ] Empty responses are parsed safely.
[ ] Content-Type is checked when needed.
[ ] Runtime validation exists at untrusted boundary.
[ ] Problem Details or equivalent error envelope is mapped.
[ ] Domain errors are displayed with actionable recovery.

[ ] Query key includes all representation-shaping inputs.
[ ] Query key includes tenant/user/permission scope where relevant.
[ ] Key is generated by factory.
[ ] List/detail/search/infinite keys are organized hierarchically.
[ ] No cache key contains raw PII unless unavoidable and reviewed.

[ ] staleTime is chosen intentionally.
[ ] gcTime is bounded for high-cardinality data.
[ ] Refetch-on-focus/reconnect is appropriate.
[ ] Background refetch preserves last-known-good data.
[ ] Initial loading and refresh loading are different UI states.

[ ] Duplicate submit is controlled.
[ ] Pending state is visible.
[ ] Optimistic update has snapshot and rollback.
[ ] Unknown outcome is handled for high-risk commands.
[ ] Conflict response has a recovery flow.
[ ] Mutation response is reconciled with cache.
[ ] Affected query invalidation is explicit.

[ ] No secret is sent to browser.
[ ] PII is minimized at response contract.
[ ] Sensitive data is not placed in URL.
[ ] Cache is cleared on logout/scope switch.
[ ] Persisted cache is scoped, versioned, and reviewed.
[ ] Signed URLs have narrow scope and short TTL.
[ ] Telemetry redacts sensitive fields.

[ ] Operation name is emitted.
[ ] Request ID is included or captured.
[ ] Trace context is propagated where supported.
[ ] Error taxonomy is available to logs/RUM.
[ ] Cache hit/miss/refetch source is observable.
[ ] Retry count and final outcome are observable.

[ ] Happy path test exists.
[ ] 400/401/403/404/409/412/422/429/5xx tests exist as relevant.
[ ] Timeout/abort test exists where relevant.
[ ] Race-order test exists for changing params/search/autosave.
[ ] Cache invalidation test proves stale UI does not survive mutation.
[ ] Contract drift test exists for generated/typed clients.

What resource does this endpoint represent?
What shape is returned?
What inputs change the representation?
Is the URL canonical?
Is this a read model or command result?

GET /api/getStuff?id=123&type=full

GET /api/tenants/{tenantId}/cases/{caseId}?include=timeline,assignees

Does GET mutate anything?
Is PUT/PATCH/POST used intentionally?
Does DELETE return 204 or representation?
Does validation use 400, 422, or domain-specific Problem Details consistently?
Does conflict use 409 or 412?
Does rate limit use 429 with Retry-After?

{
  "type": "https://example.com/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/requests/req_123",
  "code": "CASE_VALIDATION_FAILED",
  "fieldErrors": {
    "dueDate": ["Due date must be in the future."]
  }
}

The client must be able to map errors to UI behavior without parsing prose.

add optional response fields
add optional request fields
add enum values only with client fallback
add endpoints before replacing old ones

contract diff
consumer impact analysis
dual-read or dual-write phase
feature flag
rollout metric
rollback plan

onSuccess: (result, input, _context, client) => {
  client.setQueryData(caseKeys.detail(input.tenantId, input.caseId), result.case);

  client.invalidateQueries({ queryKey: caseKeys.lists(input.tenantId) });
  client.invalidateQueries({ queryKey: dashboardKeys.workload(input.tenantId) });
  client.invalidateQueries({ queryKey: userKeys.workload(input.tenantId, result.assigneeId) });
}

[ ] Is first loading different from background refresh?
[ ] Can empty success be distinguished from error?
[ ] Can stale data remain visible during refetch?
[ ] Does refresh failure destroy useful data unnecessarily?
[ ] Is optimistic state visually clear when needed?
[ ] Does conflict have a recovery path?
[ ] Does 403 after previously visible data remove sensitive content?
[ ] Are disabled controls explained?
[ ] Are loading/error states accessible?

if (isLoading) return <Spinner />;
if (error) return <Error />;
return <Data />;

if (query.status === 'loading') return <Skeleton />;

if (query.status === 'error') {
  return <BlockingError error={query.error} onRetry={query.refetch} />;
}

return (
  <section aria-busy={query.isFetching}>
    {query.isFetching && <RefreshIndicator />}
    {query.refreshError && <NonBlockingWarning error={query.refreshError} />}
    {query.data.items.length === 0 ? <EmptyState /> : <ResultList items={query.data.items} />}
  </section>
);

Page useful at T = max(required data dependencies + render + hydration + main-thread work)

route waterfall depth
number of critical requests
number of non-critical requests
largest payload size
duplicated payload fields
cache hit rate
background refetch rate
retry amplification
prefetch hit rate
hydration duplicate fetch count
LCP impact
INP impact

GET /me
  -> GET /permissions
    -> GET /dashboard
      -> GET /widgets
        -> GET /widgets/1
        -> GET /widgets/2
        -> GET /widgets/3

What crosses into the browser?

Does the current UI need this field?
Can this field be derived server-side?
Is this field sensitive for some roles?
Should this field be masked/redacted?
Will this field end up in logs, cache, URLs, telemetry, screenshots, or export?

{
  "id": "case_123",
  "title": "Case A",
  "internalRiskScore": 94,
  "investigatorNotes": "...",
  "citizenNationalId": "..."
}

{
  "id": "case_123",
  "title": "Case A"
}

function onAuthScopeChanged(client: QueryClient) {
  client.clear();
  clearPersistedQueryCache();
  clearOfflineOutboxForPreviousScope();
}

type RealtimeEvent = {
  id: string;
  type: string;
  tenantId: string;
  resourceType: string;
  resourceId: string;
  version?: number;
  occurredAt: string;
  payload?: unknown;
};

[ ] Does each event have a stable ID?
[ ] Can the client dedupe events?
[ ] Is ordering defined per stream, resource, or tenant?
[ ] Is there a resume cursor?
[ ] What happens after a gap?
[ ] What happens after reconnect?
[ ] What happens after permission revocation?
[ ] Are events validated at runtime?
[ ] Does event payload patch cache or trigger invalidation?
[ ] Does optimistic mutation know how to reconcile confirmation event?

Patch only when the event is complete, ordered, authorized, and version-safe.
Invalidate/refetch when unsure.

Can this command be safely delayed?
Can this command be safely replayed?
Can this command conflict?
Can the user understand pending state?
Can the server dedupe it?
Can audit history represent delayed intent vs delayed commit?

type OutboxCommand = {
  operationId: string;
  idempotencyKey: string;
  type: string;
  tenantId: string;
  userId: string;
  createdAt: string;
  payload: unknown;
  attempt: number;
  status: 'pending' | 'replaying' | 'succeeded' | 'failed' | 'conflict';
};

type ClientNetworkEvent = {
  eventType: 'request.start' | 'request.success' | 'request.error';
  operationName: string;
  requestId?: string;
  traceId?: string;
  routeId?: string;
  queryHash?: string;
  mutationId?: string;
  method?: string;
  status?: number;
  errorKind?: string;
  durationMs?: number;
  retryCount?: number;
  cacheState?: 'hit' | 'miss' | 'stale' | 'background-refetch';
  refetchSource?: 'mount' | 'focus' | 'reconnect' | 'poll' | 'invalidation' | 'manual';
};

API error rate by operation
API latency by operation and route
Client parse/contract error rate
Mutation rollback rate
429/rate-limit events
Retry amplification
Focus/reconnect refetch volume
Cache hit/stale/refetch rate
Hydration duplicate fetch count
Realtime reconnect/gap count
Offline outbox backlog
Top query keys by memory/data size

user action
  -> client event
  -> request ID
  -> backend trace
  -> server logs
  -> database/audit event
  -> response
  -> client cache update

[ ] Is server change additive?
[ ] Can old client still work?
[ ] Can new client handle old server response during rollout?
[ ] Is feature behind a remotely disable-able flag?
[ ] Are metrics segmented by client version?
[ ] Is there a rollback path that does not require app store/browser cache purge?
[ ] Are cache keys versioned if representation changed incompatibly?
[ ] Are persisted caches migrated or cleared?

No request sent
Request blocked by browser
Request sent but pending
Request failed network
Request returned HTTP error
Response malformed
Client parsed correctly but cache wrong
Cache correct but UI wrong
Mutation outcome unknown
Realtime stream stale/gapped
Service worker/CDN served old asset/data

route
operation name
query key or mutation ID
request URL/method/status
request ID / trace ID
timing
headers relevant to cache/CORS/auth
response body or error envelope if safe
client version
tenant/user scope if safe
browser/version
network condition

intent
UI handler
query/mutation/router/server action
API client
browser policy
transport
edge/CDN
backend
database/workflow
response parser
cache update
render

disable feature flag
increase staleTime temporarily to reduce load
turn off polling/realtime subscription
disable optimistic update
force cache clear on scope transition
route traffic away from bad edge region
rollback API response change
serve compatibility response

one better invariant
one better test
one better telemetry signal
one documented failure mode

1. Route owns navigation-critical data.
2. Query cache owns server-state replicas.
3. Forms own local drafts until submission.
4. Mutations are command lifecycles with explicit impact maps.
5. API client owns transport, parsing, error classification, timeout, and tracing.
6. Runtime validation exists at trust boundaries.
7. Cache keys include tenant/user/scope and representation inputs.
8. Server exposes structured errors and conflict information.
9. Realtime events patch only version-safe resources; otherwise invalidate.
10. Security-sensitive data is removed, not merely invalidated, on scope change.

A regulatory case dashboard.

Users can:
- filter cases by status, priority, assignee, region
- open a case detail panel
- assign a case to another investigator
- add a timeline note
- receive realtime updates when case status changes
- continue drafting a note during temporary network loss
- download an evidence file using a signed URL
- switch tenant/account context

route data
query keys
API contracts
mutation impact matrix
optimistic update rules
conflict handling
realtime event envelope
offline behavior
signed URL flow
cache clearing rules
PII minimization
observability events
test plan

Use React Query and WebSocket.

These are the resource identities, freshness policies, command lifecycles, consistency boundaries, browser policy constraints, security surfaces, and evidence paths.

Where is the source of truth?
What exactly crossed the network?
What can be stale?
What can be retried?
What can be cached?
What can be exposed?
What can conflict?
What happens if the request succeeds but the response is lost?
What happens if the user changes tenant during refetch?
What happens if a realtime event arrives before mutation response?
What evidence will exist during production incident?

A React client-server boundary is production-ready only when correctness, performance, security, UX, and observability are designed together.