website refactor

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

@@ -2,25 +2,39 @@ import { Result } from "../Result";
 
 /**
  * PageQuery contract interface
- * 
+ *
  * Defines the canonical contract for all server-side page queries.
- * 
- * Based on WEBSITE_PAGE_QUERIES.md:
+ *
+ * Architecture:
  * - Server-side composition classes
- * - Call services that call apps/api
- * - Assemble a Page DTO
- * - Explicit result describing route outcome
+ * - Construct Services manually (no DI container)
+ * - Services create their own dependencies (API Client, Logger, ErrorReporter)
+ * - Services return Result<ApiDto, DomainError>
+ * - PageQuery maps DomainError → PresentationError
+ * - PageQuery returns Result<ViewData, PresentationError>
  * - Do not implement business rules
- * 
- * @template TApiDto - The API DTO type this query produces
+ *
+ * @template TViewData - The ViewData type this query produces for templates
  * @template TParams - The parameters required to execute this query
+ * @template TError - The error type (default: string for backward compatibility)
  */
-export interface PageQuery<TApiDto, TParams = void> {
+export interface PageQuery<TViewData, TParams = void, TError = string> {
   /**
    * Execute the page query
-   * 
+   *
+   * Manual construction pattern:
+   * ```typescript
+   * const service = new MyService();
+   * const result = await service.getData();
+   * if (result.isErr()) {
+   *   return Result.err(mapToPresentationError(result.error));
+   * }
+   * const viewData = MyViewDataBuilder.build(result.value);
+   * return Result.ok(viewData);
+   * ```
+   *
    * @param params - Parameters required for query execution
-   * @returns Promise resolving to a Result
+   * @returns Promise<Result<ViewData, TError>>
    */
-  execute(params: TParams): Promise<Result<TApiDto, string>>;
+  execute(params: TParams): Promise<Result<TViewData, TError>>;
 }