view data fixes

docs/architecture/website/VIEW_DATA.md

@@ -86,8 +86,18 @@ ViewModels are built from ViewData, not from DTOs. This ensures:
 - ViewModels can be initialized from any source that provides ViewData
 - The ViewModel layer is purely for client-side interactive state
 
+**Important:** ViewData MUST NOT contain ViewModel instances. ViewModels are classes with logic; ViewData is plain JSON.
+
 ## 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.
+
+### The "Redundancy" Question
+DTOs, ViewData, and ViewModels might share similar fields, but they are NOT redundant:
+1. **DTO:** Raw API contract (Backend owned).
+2. **ViewData:** Page-specific "bag of data" (Server-to-Client transport).
+3. **ViewModel:** Interactive UI logic and computed properties (Client owned).
+
+Using all three ensures that a change in the API doesn't break the Template, and a change in UI logic doesn't require a server-side deployment.

docs/architecture/website/WEBSITE_DATA_FLOW.md

@@ -28,16 +28,29 @@ API Transport DTO
   ↓
 ViewData Builder (lib/builders/view-data/)
   ↓
-ViewData
+ViewData (Plain JSON)
   ↓
 Template
 ```
 
-### Client Components
+### Client Components (Hydration / Interactive)
+```text
+Client Wrapper / Component
+  ↓
+ViewData (from Props)
+  ↓
+ViewModel (lib/view-models/) -- [new ViewModel(viewData)]
+  ↓
+Display Objects (lib/display-objects/) -- [formatting]
+  ↓
+Interactive UI State
+```
+
+### Client Components (Direct Fetch)
 ```text
 Client Component
   ↓
-API client (useEffect)
+API client (useEffect / useQuery)
   ↓
 API Transport DTO
   ↓