gridpilot.gg/docs/architecture/website/WEBSITE_RSC_PRESENTATION.md

Website RSC Presentation Architecture (Strict)

This document defines the only allowed presentation architecture for apps/website (Next.js App Router).

It is website-only and does not change apps/api or core architecture.

Authoritative contract: WEBSITE_CONTRACT.md.

1) Core rule: API owns business truth

• apps/api is the only source of truth for business rules and canonical filtering/sorting.
• apps/website is presentation infrastructure: composition, routing, caching, and rendering.

2) The three website presentation data types

2.1 Page DTO

Purpose: server-to-client payload.

Rules:

• JSON-serializable only.
• Contains raw values only (ISO date strings, numbers, codes).
• MUST NOT contain class instances.

2.2 ViewModel

Purpose: client-only presentation model.

Rules:

• Class-based.
• Instantiated only in 'use client' modules.
• Composes Display Objects.
• NEVER passed into Templates.

2.3 ViewData

Purpose: Template input.

Rules:

• JSON-serializable only.
• Contains only values ready to render (mostly strings/numbers).
• Built from Page DTO (initial render) and from ViewModel (post-hydration).

The mapping between Page DTO, ViewModel, and ViewData is performed by Presenters. See PRESENTERS.md.

3) Required per-route structure

Every route MUST follow:

1. page.tsx (server): calls a PageQuery and passes Page DTO
2. *PageClient.tsx (client): builds ViewData and renders Template
3. *Template.tsx (pure UI): renders ViewData only

All writes enter through Server Actions. See FORM_SUBMISSION.md.

4) Authoritative specification

This document is an entry point only.

The authoritative, test-enforced spec lives at:

• plans/nextjs-rsc-viewmodels-concept.md

Final contract:

• WEBSITE_CONTRACT.md