docs: add comprehensive deep linking documentation

Changes:
- Add detailed JSDoc headers to deep linking files
- Document type system and validation strategy
- Add architecture overview and error handling docs
- Include usage examples and integration points
- Improve code organization comments

This improves maintainability by documenting the deep linking
system's architecture, type safety, and integration points.

src/services/deepLinks.ts

@@ -1,3 +1,33 @@
+/**
+ * @file Deep Link Handler Service
+ * @author Matthew Raymer
+ * 
+ * This service handles the processing and routing of deep links in the TimeSafari app.
+ * It provides a type-safe interface between the raw deep links and the application router.
+ * 
+ * Architecture:
+ * 1. DeepLinkHandler class encapsulates all deep link processing logic
+ * 2. Uses Zod schemas from types/deepLinks for parameter validation
+ * 3. Provides consistent error handling and logging
+ * 4. Maps validated parameters to Vue router calls
+ * 
+ * Error Handling Strategy:
+ * - All errors are wrapped in DeepLinkError interface
+ * - Errors include error codes for systematic handling
+ * - Detailed error information is logged for debugging
+ * - Errors are propagated to the global error handler
+ * 
+ * Validation Strategy:
+ * - URL structure validation
+ * - Route-specific parameter validation using Zod schemas
+ * - Query parameter validation and sanitization
+ * - Type-safe parameter passing to router
+ * 
+ * @example
+ * const handler = new DeepLinkHandler(router);
+ * await handler.handleDeepLink("timesafari://claim/123?view=details");
+ */
+
 import { Router } from "vue-router";
 import { deepLinkSchemas, DeepLinkParams } from "../types/deepLinks";
 import { logConsoleAndDb } from "../db";