About
An educational project about how Next.js moves data
Most explanations of Server Components, Server Actions and caching are either diagrams that never run, or running code with no diagram. This project is both at once.
The goal
I wanted a way to see what happens between a form submit and an updated list in the Next.js App Router: where the request goes, which cache answers, what the response contains, and what React does with it. The same questions apply to theme preferences (why cookies can be read before the first byte of HTML and localStorage cannot) and to component boundaries (what a 'use client' directive really drags into the browser bundle).
The result is an interactive architecture map, three tutorials that run the real runtime, and a narrated timeline that labels every event honestly.
Three kinds of events
- measured
- Timestamped by this app: form submits and responses in the browser; each step of the Server Action on the server. The server trace is returned with the action result.
- inferred
- Deduced from something observable. A Server Component passes two timestamps to the client: when it rendered and when its cache entry was computed. If the first changes and the second does not, that was a cache hit.
- simulation
- Scripted from the documentation. Used in the playground, for previews before your first run, and for sequences that cannot be observed from a page, such as the browser attaching a cookie to a request.
Architecture
The code is organised so that the explanation would survive without Three.js:
src/domainplain TypeScript: the architecture graph, trace event types, revalidation strategies with their documented expectations, scripted scenarios, and the component-boundary rules. No React, no Next.js imports. Fully unit tested.src/featuresthe Next.js behaviour: the product repository (in-memory or Redis), the 'use cache' query, the Server Actions, the theme demo actions and the session cookie.src/visualizationthe playback store, the 3D scene, the 2D SVG map, the stage, the transport bar, the step list and the code panel. The 3D scene and the 2D map receive identical inputs.src/appthin pages that compose the above. Embedded demo frames live in their own route group without the site chrome.
Architectural decisions and their trade-offs are written down in docs/adr; the README has the diagrams. Nothing here requires a paid service: the default repository is in-memory and labelled as ephemeral, and a free Redis can be plugged in with two environment variables.
Stack
- Next.js
- 16.4 App Router with Cache Components and Partial Prefetching
- React
- 19: Server Components, Server Functions, useActionState
- TypeScript
- strict, discriminated unions for events, strategies and diagnostics
- Tailwind CSS
- v4 with design tokens defined once in globals.css
- React Three Fiber
- the 3D architecture map, confined to src/visualization/three
- Zustand
- one small playback store shared by the map, the transport and the steps
- Zod
- validation at the Server Action boundary
- Motion
- layout and SVG animations where they help
- shiki
- server-side syntax highlighting of the real source files
- Vitest + Playwright
- domain unit tests and end-to-end checks against the production build
Author
Built by Emin Aryan, a frontend engineer who likes React, Next.js and interactive 3D. This is an independent project; it is not affiliated with or endorsed by any company.