Add models, enums, and services for user roles, theme preferences, slug history, and ID generation

memory-bank/models/LocationModel.md

@@ -0,0 +1,104 @@
+# Location Model
+
+## Overview
+The Location model provides polymorphic location management for parks, areas, and other entities in ThrillWiki. It handles geocoding, coordinate management, and location-based search capabilities.
+
+## Structure
+
+### Database Table
+- Table Name: `locations`
+- Primary Key: `id` (bigint)
+- Polymorphic Fields: `locatable_type`, `locatable_id`
+- Timestamps: `created_at`, `updated_at`
+
+### Fields
+- **Address Components**
+  - `address` (string, nullable) - Street address
+  - `city` (string) - City name
+  - `state` (string, nullable) - State/province
+  - `country` (string) - Country name
+  - `postal_code` (string, nullable) - Postal/ZIP code
+
+- **Coordinates**
+  - `latitude` (decimal, 10,8) - Latitude coordinate
+  - `longitude` (decimal, 11,8) - Longitude coordinate
+  - `elevation` (decimal, 8,2, nullable) - Elevation in meters
+
+- **Additional Details**
+  - `timezone` (string, nullable) - Location timezone
+  - `metadata` (json, nullable) - Additional location data
+  - `is_approximate` (boolean) - Indicates if location is approximate
+  - `source` (string, nullable) - Data source identifier
+
+- **Geocoding**
+  - `geocoding_data` (json, nullable) - Cached geocoding response
+  - `geocoded_at` (timestamp, nullable) - Last geocoding timestamp
+
+### Indexes
+- Coordinates: `(latitude, longitude)`
+- Location: `(country, state, city)`
+- Postal: `postal_code`
+
+## Relationships
+
+### Polymorphic
+- `locatable()` - Polymorphic relationship to parent model (Park, Area, etc.)
+
+## Accessors & Mutators
+- `coordinates` - Returns [lat, lng] array
+- `formatted_address` - Returns formatted address string
+- `map_url` - Returns Google Maps URL
+
+## Methods
+
+### Location Management
+- `updateCoordinates(float $lat, float $lng)` - Update coordinates
+- `setAddress(array $components)` - Set address components
+- `geocode()` - Trigger geocoding refresh
+- `reverseGeocode()` - Get address from coordinates
+
+### Queries
+- `scopeNearby($query, $lat, $lng, $radius)` - Find nearby locations
+- `scopeInBounds($query, $ne, $sw)` - Find locations in bounds
+- `scopeInCountry($query, $country)` - Filter by country
+- `scopeInState($query, $state)` - Filter by state
+- `scopeInCity($query, $city)` - Filter by city
+
+### Calculations
+- `distanceTo($lat, $lng)` - Calculate distance to point
+- `bearingTo($lat, $lng)` - Calculate bearing to point
+
+## Usage Examples
+
+```php
+// Create location for park
+$park->location()->create([
+    'address' => '123 Main St',
+    'city' => 'Orlando',
+    'state' => 'FL',
+    'country' => 'USA',
+    'latitude' => 28.538336,
+    'longitude' => -81.379234
+]);
+
+// Find parks within 50km
+$nearbyParks = Park::whereHas('location', function ($query) {
+    $query->nearby(28.538336, -81.379234, 50);
+})->get();
+```
+
+## Integration Points
+
+### Services
+- GeocodeService - Address/coordinate lookup
+- LocationSearchService - Advanced location search
+
+### Components
+- LocationSelector - Map-based location picker
+- LocationDisplay - Location visualization
+
+## Notes
+- Coordinates use high precision for accuracy
+- Geocoding results are cached to reduce API calls
+- Polymorphic design allows reuse across models
+- Search methods use spatial indexes for performance