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.

docs/DEEP_LINKS.md

@@ -1,4 +1,47 @@
-# TimeSafari Deep Linking
+# TimeSafari Deep Linking Documentation
+
+## Type System Overview
+
+The deep linking system uses a multi-layered type safety approach:
+
+1. **Runtime Validation (Zod Schemas)**
+   - Validates URL structure
+   - Enforces parameter requirements
+   - Sanitizes input data
+   - Provides detailed validation errors
+
+2. **TypeScript Types**
+   - Generated from Zod schemas
+   - Ensures compile-time type safety
+   - Provides IDE autocompletion
+   - Catches type errors during development
+
+3. **Router Integration**
+   - Type-safe parameter passing
+   - Route-specific parameter validation
+   - Query parameter type checking
+
+## Implementation Files
+
+- `src/types/deepLinks.ts`: Type definitions and validation schemas
+- `src/services/deepLinks.ts`: Deep link processing service
+- `src/main.capacitor.ts`: Capacitor integration
+
+## Type Safety Examples
+
+```typescript
+// Parameter type safety
+type ClaimParams = DeepLinkParams["claim"];
+// TypeScript knows this has:
+// - id: string
+// - view?: "details" | "certificate" | "raw"
+// Runtime validation
+const result = deepLinkSchemas.claim.safeParse({
+id: "123",
+view: "details"
+});
+// Validates at runtime with detailed error messages
+```
 
 ## Supported URL Schemes