Review Packet: Rendering and Data Architecture

When to use

Use this packet for route rendering decisions, server/client boundary changes, cache strategy, route loaders, BFF/API contracts, Suspense/streaming plans, offline behavior, and mutation consistency decisions.

Intake questions

• Which user journey and routes are affected?
• What must be visible on first paint?
• What must be interactive immediately?
• Which data must be fresh, eventually fresh, or user-refreshed?
• Which parts are public, authenticated, personalized, or tenant-specific?
• What work is done at build time, edge, origin, and client?
• What happens when a request is slow, stale, duplicated, or fails?

Required artifacts

• Route rendering matrix.
• Data ownership map.
• Cache and invalidation policy.
• Mutation lifecycle and rollback behavior.
• Loading/error/empty/degraded state designs.
• Performance budget for affected routes.

Decision matrix

Signal	Prefer static/cacheable	Prefer server request time	Prefer client runtime
Freshness	Content changes slowly.	User or request context matters.	User interaction drives freshness.
SEO	Public and indexable.	Public but personalized by request.	Private or not discoverable.
Interactivity	Mostly read-only.	Interactive islands.	Continuous stateful interaction.
Cost	Cheap to precompute.	Server can orchestrate efficiently.	Client responsiveness dominates.

Red flags

• One rendering mode is chosen for the entire application.
• Client state stores server-owned data without invalidation rules.
• URL state, form state, server state, and UI state are mixed together.
• Hydration cost is ignored because SSR is present.
• Cache invalidation is described as "we will clear it when needed."

Approval criteria

• Route-level rendering decisions are explicit.
• Cache keys and invalidation triggers are documented.
• Critical loading and error states are designed.
• Mutation consistency and rollback behavior are specified.
• Metrics exist to detect regressions.

Example reviewer comments

• "This route has personalized data but the cache key does not include tenant or role. Please document how cross-user leakage is prevented."
• "The dashboard shell can render before all panels resolve. Please split the all-or-nothing data dependency."
• "This optimistic update needs a conflict path when the server rejects the mutation."

Example ADR prompt

Write an ADR explaining the selected rendering model per route, freshness requirements, cache ownership, invalidation triggers, hydration cost, and fallback behavior.

Release readiness checklist

• Route rendering matrix reviewed.
• Cache policy tested with user, tenant, locale, and experiment variation.
• Mutation failures produce recoverable UI.
• Web Vitals and route errors are observable after release.
• Rollback path is documented.