website refactor

apps/website/lib/contracts/builders/ViewDataBuilder.ts

@@ -0,0 +1,25 @@
+/**
+ * ViewData Builder Contract
+ * 
+ * Purpose: Transform ViewModels into ViewData for templates
+ * 
+ * Rules:
+ * - Deterministic and side-effect free
+ * - No HTTP/API calls
+ * - Input: ViewModel
+ * - Output: ViewData (JSON-serializable)
+ * - Must be in lib/builders/view-data/
+ * - Must be named *ViewDataBuilder
+ * - Must have 'use client' directive
+ * - Must implement static build() method
+ */
+
+export interface ViewDataBuilder<TInput, TOutput> {
+  /**
+   * Transform ViewModel into ViewData
+   * 
+   * @param viewModel - Client-side ViewModel
+   * @returns ViewData for template
+   */
+  build(viewModel: TInput): TOutput;
+}

apps/website/lib/contracts/builders/ViewModelBuilder.ts

@@ -0,0 +1,25 @@
+/**
+ * ViewModel Builder Contract
+ * 
+ * Purpose: Transform API Transport DTOs into ViewModels
+ * 
+ * Rules:
+ * - Deterministic and side-effect free
+ * - No HTTP/API calls
+ * - Input: API Transport DTO
+ * - Output: ViewModel
+ * - Must be in lib/builders/view-models/
+ * - Must be named *ViewModelBuilder
+ * - Must have 'use client' directive
+ * - Must implement static build() method
+ */
+
+export interface ViewModelBuilder<TInput, TOutput> {
+  /**
+   * Transform DTO into ViewModel
+   * 
+   * @param dto - API Transport DTO
+   * @returns ViewModel
+   */
+  build(dto: TInput): TOutput;
+}

apps/website/lib/contracts/mutations/Mutation.ts

@@ -0,0 +1,33 @@
+/**
+ * Mutation Contract
+ *
+ * Purpose: Framework-agnostic write operations
+ *
+ * Rules:
+ * - Orchestrates services for writes
+ * - No HTTP/API calls directly
+ * - No 'use client' directive
+ * - No 'use server' directive
+ * - Must be in lib/mutations/
+ * - Must be named *Mutation
+ * - Can be called from Server Actions
+ * - Single responsibility: ONE operation per mutation
+ *
+ * Pattern:
+ * Server Action → Mutation → Service → API Client
+ *
+ * Design Principle:
+ * Each mutation does ONE thing. If you need multiple operations,
+ * create multiple mutation classes (e.g., UpdateUserStatusMutation, DeleteUserMutation).
+ * This follows the same pattern as Page Queries.
+ */
+
+export interface Mutation<TInput = void, TOutput = void> {
+  /**
+   * Execute the mutation
+   *
+   * @param input - Mutation input
+   * @returns Output (optional)
+   */
+  execute(input: TInput): Promise<TOutput>;
+}

apps/website/lib/contracts/page-queries/PageQuery.ts

@@ -1,4 +1,4 @@
-import { PageQueryResult } from "@/lib/page-queries/page-query-result/PageQueryResult";
+import { PageQueryResult } from "./PageQueryResult";
 
 
 /**

apps/website/lib/contracts/page-queries/PageQueryResult.ts

@@ -0,0 +1,18 @@
+/**
+ * PageQueryResult discriminated union
+ * 
+ * Canonical result type for all server-side page queries.
+ * Defines the explicit outcome of a page query execution.
+ * 
+ * Based on WEBSITE_PAGE_QUERIES.md:
+ * - ok with { dto }
+ * - notFound
+ * - redirect with { to }
+ * - error with { errorId }
+ */
+
+export type PageQueryResult<TPageDto> =
+  | { status: 'ok'; dto: TPageDto }
+  | { status: 'notFound' }
+  | { status: 'redirect'; to: string }
+  | { status: 'error'; errorId: string };