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

ViewData (Website Templates)

ViewData is the only allowed input type for Templates in apps/website.

Authoritative contract: WEBSITE_CONTRACT.md.

1) Definition

ViewData is a JSON-serializable, template-ready data structure:

• primitives (strings/numbers/booleans)
• arrays and plain objects
• null for missing values

2) What ViewData is NOT

ViewData is not:

• an API Transport DTO (raw transport)
• a ViewModel (client-only class)
• a Display Object instance

3) Construction rules

ViewData is created by ViewData Builders:

Server Components (RSC)

const apiDto = await PageQuery.execute();
const viewData = ViewDataBuilder.build(apiDto);
return <Template viewData={viewData} />;

Client Components

'use client';

const [viewModel, setViewModel] = useState<ViewModel | null>(null);

useEffect(() => {
  const apiDto = await apiClient.get();
  const viewData = ViewDataBuilder.build(apiDto);
  const vm = ViewModelBuilder.build(viewData);
  setViewModel(vm);
}, []);

// Template receives ViewData directly
return viewModel ? <Template viewData={viewData} /> : null;

Templates MUST NOT compute derived values.

ViewData Builders MUST NOT call the API.

Important: ViewModels are built from ViewData, not directly from DTOs. This ensures ViewModels are decoupled from the API transport layer.

4) Formatting and SEO

ViewData is responsible for providing fully formatted strings to Templates for Server-Side Rendering (SSR).

• SEO Requirement: All data required for search engines (prices, dates, counts, labels) MUST be formatted in the ViewData Builder on the server.
• Template Simplicity: Templates should simply render the strings provided in ViewData without further processing.

5) Determinism rules

Any formatting used to produce ViewData MUST be deterministic.

Forbidden anywhere in formatting code paths:

• Intl.*
• Date.toLocaleString() / Date.toLocaleDateString() / Date.toLocaleTimeString()

Reason: SSR and browser outputs can differ.

Localization MUST NOT depend on runtime locale APIs. If localized strings are required, they MUST be provided as deterministic inputs (for example via API-provided labels or a deterministic code-to-label map) and passed through ViewData Builders into ViewData.

5) Relationship to ViewModels

ViewData serves as the stable, serializable contract between the server and client. It is:

• The input for Templates (both SSR and Client)
• The input for ViewModelBuilders (Client-side state initialization)

ViewModels are built from ViewData, not from DTOs. This ensures:

• ViewModels remain decoupled from API transport concerns
• ViewModels can be initialized from any source that provides ViewData
• The ViewModel layer is purely for client-side interactive state

6) Relationship to Display Objects

Display Objects are used to implement formatting/mapping, but their instances MUST NOT be stored inside ViewData.

Only primitive outputs produced by Display Objects may appear in ViewData.