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

Website Data Flow (Strict)

This document defines the apps/website data flow.

Authoritative contract: docs/architecture/website/WEBSITE_CONTRACT.md.

Website scope:

• apps/website/**

1) Website role

The website is a delivery layer.

It renders truth from the API and forwards user intent to the API.

2) Read flow

Server Components (RSC)

RSC page.tsx
  ↓
PageQuery
  ↓
API client (infra)
  ↓
API Transport DTO
  ↓
ViewData Builder (lib/builders/view-data/)
  ↓
Formatters (lib/display-objects/) -- [primitive output]
  ↓
ViewData (Plain JSON)
  ↓
Template

Client Components (Hydration / Interactive)

Client Wrapper / Component
  ↓
ViewData (from Props)
  ↓
ViewModel (lib/view-models/) -- [new ViewModel(viewData)]
  ↓
Display Objects (lib/display-objects/) -- [rich API]
  ↓
Interactive UI State

Client Components (Direct Fetch)

Client Component
  ↓
API client (useEffect / useQuery)
  ↓
API Transport DTO
  ↓
ViewModel Builder (lib/builders/view-models/)
  ↓
ViewModel (lib/view-models/)
  ↓
Client State (useState)
  ↓
Template

3) Write flow

All writes enter through Server Actions.

User intent
  ↓
Server Action
  ↓
Command Model / Request DTO
  ↓
API
  ↓
Revalidation
  ↓
RSC reload

4) Non-negotiable rules

1. Templates accept ViewData only.
2. Page Queries do not format.
3. ViewData Builders transform API DTO → ViewData (RSC).
4. ViewModel Builders transform API DTO → ViewModel (Client).
5. Builders do not call the API.
6. Client state is UI-only.