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

memory-bank/features/LocationSystem.md

@@ -0,0 +1,238 @@
+# Location System
+
+## Overview
+The Location System provides comprehensive location management for parks, areas, and other entities through polymorphic relationships. It includes geocoding, map integration, and location-based search capabilities.
+
+## Components
+
+### 1. Database Structure
+
+#### Locations Table
+```sql
+CREATE TABLE locations (
+    id bigint PRIMARY KEY,
+    locatable_type varchar(255),
+    locatable_id bigint,
+    address varchar(255) NULL,
+    city varchar(255),
+    state varchar(255) NULL,
+    country varchar(255),
+    postal_code varchar(255) NULL,
+    latitude decimal(10,8),
+    longitude decimal(11,8),
+    elevation decimal(8,2) NULL,
+    timezone varchar(255) NULL,
+    metadata json NULL,
+    is_approximate boolean DEFAULT false,
+    source varchar(255) NULL,
+    geocoding_data json NULL,
+    geocoded_at timestamp NULL,
+    created_at timestamp,
+    updated_at timestamp,
+    
+    INDEX idx_coordinates (latitude, longitude),
+    INDEX idx_location (country, state, city),
+    INDEX idx_postal (postal_code)
+);
+```
+
+### 2. Models
+
+#### Location Model
+- Polymorphic relationships
+- Geocoding integration
+- Coordinate handling
+- Distance calculations
+
+#### HasLocation Trait
+- Location relationship
+- Coordinate accessors
+- Distance methods
+- Map integration
+
+### 3. Services
+
+#### GeocodeService
+- Address lookup
+- Coordinate validation
+- Batch processing
+- Cache management
+
+#### LocationSearchService
+- Distance-based search
+- Boundary queries
+- Clustering support
+- Performance optimization
+
+### 4. Components
+
+#### LocationSelector
+- Map integration
+- Address search
+- Coordinate picker
+- Validation feedback
+
+#### LocationDisplay
+- Map rendering
+- Marker clustering
+- Info windows
+- Interactive controls
+
+## Implementation Details
+
+### 1. Model Structure
+```php
+class Location extends Model
+{
+    protected $fillable = [
+        'address',
+        'city',
+        'state',
+        'country',
+        'postal_code',
+        'latitude',
+        'longitude',
+        'elevation',
+        'timezone',
+        'metadata',
+        'is_approximate',
+        'source',
+        'geocoding_data',
+        'geocoded_at',
+    ];
+
+    protected $casts = [
+        'latitude' => 'decimal:8',
+        'longitude' => 'decimal:8',
+        'elevation' => 'decimal:2',
+        'metadata' => 'array',
+        'geocoding_data' => 'array',
+        'geocoded_at' => 'datetime',
+        'is_approximate' => 'boolean',
+    ];
+}
+```
+
+### 2. Trait Implementation
+```php
+trait HasLocation
+{
+    public function location()
+    {
+        return $this->morphOne(Location::class, 'locatable');
+    }
+
+    public function getCoordinatesAttribute()
+    {
+        return [
+            'lat' => $this->location?->latitude,
+            'lng' => $this->location?->longitude,
+        ];
+    }
+}
+```
+
+## Integration Points
+
+### 1. Parks System
+- Location assignment
+- Map display
+- Area boundaries
+- Distance calculations
+
+### 2. Search System
+- Location-based filtering
+- Distance sorting
+- Boundary queries
+- Clustering support
+
+### 3. API Integration
+- Geocoding services
+- Map providers
+- Data validation
+- Error handling
+
+## Performance Considerations
+
+### 1. Database Design
+- Efficient indexes
+- Coordinate precision
+- Query optimization
+- Cache strategy
+
+### 2. Geocoding
+- Request limiting
+- Cache management
+- Batch processing
+- Error handling
+
+### 3. Map Integration
+- Lazy loading
+- Marker clustering
+- Viewport management
+- Memory optimization
+
+## Future Enhancements
+
+1. [ ] Add route planning
+2. [ ] Implement geofencing
+3. [ ] Add location sharing
+4. [ ] Create heatmaps
+5. [ ] Add offline support
+6. [ ] Implement navigation
+7. [ ] Add location history
+8. [ ] Create location alerts
+
+## Security Considerations
+
+### 1. Data Protection
+- Coordinate validation
+- Input sanitization
+- Access control
+- Audit logging
+
+### 2. API Security
+- Rate limiting
+- Token management
+- Error handling
+- Request validation
+
+## Testing Strategy
+
+### 1. Unit Tests
+- [ ] Coordinate validation
+- [ ] Distance calculations
+- [ ] Geocoding integration
+- [ ] Model relationships
+
+### 2. Integration Tests
+- [ ] Map integration
+- [ ] Search functionality
+- [ ] API communication
+- [ ] Cache management
+
+### 3. Performance Tests
+- [ ] Large datasets
+- [ ] Clustering efficiency
+- [ ] Query optimization
+- [ ] Memory usage
+
+## Monitoring
+
+### 1. Performance Metrics
+- [ ] Query timing
+- [ ] API response times
+- [ ] Cache hit rates
+- [ ] Memory usage
+
+### 2. Error Tracking
+- [ ] Geocoding failures
+- [ ] API errors
+- [ ] Invalid coordinates
+- [ ] Cache misses
+
+### 3. Usage Analytics
+- [ ] Search patterns
+- [ ] Popular locations
+- [ ] API usage
+- [ ] User interactions