From f4f8ec8f9be05268ae882bbcb5297bfe40164164 Mon Sep 17 00:00:00 2001
From: pacnpal <183241239+pacnpal@users.noreply.github.com>
Date: Tue, 19 Aug 2025 18:51:33 -0400
Subject: [PATCH] Configure PostgreSQL with PostGIS support
- Updated database settings to use dj_database_url for environment-based configuration
- Added dj-database-url dependency
- Configured PostGIS backend for spatial data support
- Set default DATABASE_URL for production PostgreSQL connection
---
.github-pat | 1 +
.../config/.github-pat.20250818_210101.backup | 1 +
...wiki-automation.env.20250818_210101.backup | 203 +
debug-setup-automation.sh | 91 +
parks_listing_comprehensive_documentation.md | 313 +
parks_listing_improvement_plan.md | 700 ++
scripts/systemd/thrillwiki-automation.env | 203 +
.../systemd/thrillwiki-automation.env.example | 296 +
scripts/systemd/thrillwiki-automation.service | 106 +
scripts/systemd/thrillwiki-deployment.env | 321 +
scripts/systemd/thrillwiki-deployment.service | 103 +
.../systemd/thrillwiki-smart-deploy.service | 76 +
scripts/systemd/thrillwiki-smart-deploy.timer | 17 +
scripts/vm/README.md | 482 ++
scripts/vm/automation-config.sh | 838 ++
scripts/vm/bulletproof-automation.sh | 1156 +++
scripts/vm/deploy-automation.sh | 560 ++
scripts/vm/deploy-complete.sh | 7145 +++++++++++++++++
scripts/vm/diagnose-systemd-architecture.sh | 113 +
.../vm/emergency-fix-systemd-architecture.sh | 264 +
scripts/vm/fix-missing-deploy-script.sh | 175 +
scripts/vm/fix-systemd-service-config.sh | 223 +
scripts/vm/fix-systemd-services.sh | 307 +
scripts/vm/github-setup.py | 632 ++
scripts/vm/quick-start.sh | 712 ++
scripts/vm/remote-deploy.sh | 2685 +++++++
scripts/vm/run-remote-systemd-diagnosis.sh | 94 +
scripts/vm/setup-automation.sh | 1047 +++
scripts/vm/test-deployment-presets.sh | 355 +
scripts/vm/test-env-fix.sh | 259 +
scripts/vm/test-github-auth-diagnosis.sh | 146 +
scripts/vm/test-github-auth-fix.sh | 274 +
scripts/vm/test-shell-compatibility.sh | 193 +
scripts/vm/test-ssh-auth-fix.sh | 135 +
scripts/vm/test-step4b-compatibility.sh | 304 +
scripts/vm/test-step5a-compatibility.sh | 642 ++
scripts/vm/test-step5a-simple.sh | 227 +
scripts/vm/test-step5b-final-validation.sh | 917 +++
scripts/vm/test-systemd-service-diagnosis.sh | 162 +
scripts/vm/test-validation-fix.sh | 174 +
scripts/vm/validate-step5b-simple.sh | 158 +
static/css/tailwind.css | 6 +
test-args.sh | 43 +
thrillwiki/settings.py | 18 +-
44 files changed, 22869 insertions(+), 8 deletions(-)
create mode 100644 .github-pat
create mode 100644 backups/config/.github-pat.20250818_210101.backup
create mode 100644 backups/config/thrillwiki-automation.env.20250818_210101.backup
create mode 100755 debug-setup-automation.sh
create mode 100644 parks_listing_comprehensive_documentation.md
create mode 100644 parks_listing_improvement_plan.md
create mode 100644 scripts/systemd/thrillwiki-automation.env
create mode 100644 scripts/systemd/thrillwiki-automation.env.example
create mode 100644 scripts/systemd/thrillwiki-automation.service
create mode 100644 scripts/systemd/thrillwiki-deployment.env
create mode 100644 scripts/systemd/thrillwiki-deployment.service
create mode 100644 scripts/systemd/thrillwiki-smart-deploy.service
create mode 100644 scripts/systemd/thrillwiki-smart-deploy.timer
create mode 100644 scripts/vm/README.md
create mode 100755 scripts/vm/automation-config.sh
create mode 100755 scripts/vm/bulletproof-automation.sh
create mode 100755 scripts/vm/deploy-automation.sh
create mode 100755 scripts/vm/deploy-complete.sh
create mode 100755 scripts/vm/diagnose-systemd-architecture.sh
create mode 100755 scripts/vm/emergency-fix-systemd-architecture.sh
create mode 100755 scripts/vm/fix-missing-deploy-script.sh
create mode 100755 scripts/vm/fix-systemd-service-config.sh
create mode 100755 scripts/vm/fix-systemd-services.sh
create mode 100755 scripts/vm/github-setup.py
create mode 100755 scripts/vm/quick-start.sh
create mode 100755 scripts/vm/remote-deploy.sh
create mode 100755 scripts/vm/run-remote-systemd-diagnosis.sh
create mode 100755 scripts/vm/setup-automation.sh
create mode 100755 scripts/vm/test-deployment-presets.sh
create mode 100755 scripts/vm/test-env-fix.sh
create mode 100755 scripts/vm/test-github-auth-diagnosis.sh
create mode 100755 scripts/vm/test-github-auth-fix.sh
create mode 100755 scripts/vm/test-shell-compatibility.sh
create mode 100755 scripts/vm/test-ssh-auth-fix.sh
create mode 100755 scripts/vm/test-step4b-compatibility.sh
create mode 100755 scripts/vm/test-step5a-compatibility.sh
create mode 100755 scripts/vm/test-step5a-simple.sh
create mode 100755 scripts/vm/test-step5b-final-validation.sh
create mode 100755 scripts/vm/test-systemd-service-diagnosis.sh
create mode 100755 scripts/vm/test-validation-fix.sh
create mode 100755 scripts/vm/validate-step5b-simple.sh
create mode 100755 test-args.sh
diff --git a/.github-pat b/.github-pat
new file mode 100644
index 00000000..b80d277c
--- /dev/null
+++ b/.github-pat
@@ -0,0 +1 @@
+[GITHUB-TOKEN-REMOVED]
diff --git a/backups/config/.github-pat.20250818_210101.backup b/backups/config/.github-pat.20250818_210101.backup
new file mode 100644
index 00000000..630c5d5e
--- /dev/null
+++ b/backups/config/.github-pat.20250818_210101.backup
@@ -0,0 +1 @@
+[GITHUB-TOKEN-REMOVED]
\ No newline at end of file
diff --git a/backups/config/thrillwiki-automation.env.20250818_210101.backup b/backups/config/thrillwiki-automation.env.20250818_210101.backup
new file mode 100644
index 00000000..c06fa181
--- /dev/null
+++ b/backups/config/thrillwiki-automation.env.20250818_210101.backup
@@ -0,0 +1,203 @@
+# ThrillWiki Automation Service Environment Configuration
+# Copy this file to thrillwiki-automation***REMOVED*** and customize for your environment
+#
+# Security Note: This file should have restricted permissions (600) as it may contain
+# sensitive information like GitHub Personal Access Tokens
+
+# [AWS-SECRET-REMOVED]====================================
+# PROJECT CONFIGURATION
+# [AWS-SECRET-REMOVED]====================================
+
+# Base project directory (usually auto-detected)
+# PROJECT_DIR=/home/ubuntu/thrillwiki
+
+# Service name for systemd integration
+# SERVICE_NAME=thrillwiki
+
+# [AWS-SECRET-REMOVED]====================================
+# GITHUB REPOSITORY CONFIGURATION
+# [AWS-SECRET-REMOVED]====================================
+
+# GitHub repository remote name
+# GITHUB_REPO=origin
+
+# Branch to pull from
+# GITHUB_BRANCH=main
+
+# GitHub Personal Access Token (PAT) - Required for private repositories
+# Generate at: https://github.com/settings/tokens
+# Required permissions: repo (Full control of private repositories)
+# GITHUB_TOKEN=ghp_your_personal_access_token_here
+
+# GitHub token file location (alternative to GITHUB_TOKEN)
+# GITHUB_TOKEN_FILE=/home/ubuntu/thrillwiki/.github-pat
+
+# [AWS-SECRET-REMOVED]====================================
+# AUTOMATION TIMING CONFIGURATION
+# [AWS-SECRET-REMOVED]====================================
+
+# Repository pull interval in seconds (default: 300 = 5 minutes)
+# PULL_INTERVAL=300
+
+# Health check interval in seconds (default: 60 = 1 minute)
+# HEALTH_CHECK_INTERVAL=60
+
+# Server startup timeout in seconds (default: 120 = 2 minutes)
+# STARTUP_TIMEOUT=120
+
+# Restart delay after failure in seconds (default: 10)
+# RESTART_DELAY=10
+
+# [AWS-SECRET-REMOVED]====================================
+# LOGGING CONFIGURATION
+# [AWS-SECRET-REMOVED]====================================
+
+# Log directory (default: project_dir/logs)
+# LOG_DIR=/home/ubuntu/thrillwiki/logs
+
+# Log file path
+# LOG_[AWS-SECRET-REMOVED]proof-automation.log
+
+# Maximum log file size in bytes (default: 10485760 = 10MB)
+# MAX_LOG_SIZE=10485760
+
+# Lock file location to prevent multiple instances
+# LOCK_FILE=/tmp/thrillwiki-bulletproof.lock
+
+# [AWS-SECRET-REMOVED]====================================
+# DEVELOPMENT SERVER CONFIGURATION
+# [AWS-SECRET-REMOVED]====================================
+
+# Server host address (default: 0.0.0.0 for all interfaces)
+# SERVER_HOST=0.0.0.0
+
+# Server port (default: 8000)
+# SERVER_PORT=8000
+
+# [AWS-SECRET-REMOVED]====================================
+# DJANGO CONFIGURATION
+# [AWS-SECRET-REMOVED]====================================
+
+# Django settings module
+# DJANGO_SETTINGS_MODULE=thrillwiki.settings
+
+# Python path
+# PYTHONPATH=/home/ubuntu/thrillwiki
+
+# [AWS-SECRET-REMOVED]====================================
+# ADVANCED CONFIGURATION
+# [AWS-SECRET-REMOVED]====================================
+
+# GitHub authentication script location
+# GITHUB_AUTH_[AWS-SECRET-REMOVED]ithub-auth.py
+
+# Enable verbose logging (true/false)
+# VERBOSE_LOGGING=false
+
+# Enable debug mode for troubleshooting (true/false)
+# DEBUG_MODE=false
+
+# Custom git remote URL (overrides GITHUB_REPO if set)
+# CUSTOM_GIT_REMOTE=https://github.com/username/repository.git
+
+# Email notifications for critical failures (requires email configuration)
+# NOTIFICATION_EMAIL=admin@example.com
+
+# Maximum consecutive failures before alerting (default: 5)
+# MAX_CONSECUTIVE_FAILURES=5
+
+# Enable automatic dependency updates (true/false, default: true)
+# AUTO_UPDATE_DEPENDENCIES=true
+
+# Enable automatic migrations on code changes (true/false, default: true)
+# AUTO_MIGRATE=true
+
+# Enable automatic static file collection (true/false, default: true)
+# AUTO_COLLECTSTATIC=true
+
+# [AWS-SECRET-REMOVED]====================================
+# SECURITY CONFIGURATION
+# [AWS-SECRET-REMOVED]====================================
+
+# GitHub authentication method (token|ssh|https)
+# Default: token (uses GITHUB_TOKEN or GITHUB_TOKEN_FILE)
+# GITHUB_AUTH_METHOD=token
+
+# SSH key path for git operations (when using ssh auth method)
+# SSH_KEY_PATH=/home/ubuntu/.ssh/***REMOVED***
+
+# Git user configuration for commits
+# GIT_USER_NAME="ThrillWiki Automation"
+# GIT_USER_EMAIL="automation@thrillwiki.local"
+
+# [AWS-SECRET-REMOVED]====================================
+# MONITORING AND HEALTH CHECKS
+# [AWS-SECRET-REMOVED]====================================
+
+# Health check URL to verify server is running
+# HEALTH_CHECK_URL=http://localhost:8000/health/
+
+# Health check timeout in seconds
+# HEALTH_CHECK_TIMEOUT=30
+
+# Enable system resource monitoring (true/false)
+# MONITOR_RESOURCES=true
+
+# Memory usage threshold for warnings (in MB)
+# MEMORY_WARNING_THRESHOLD=1024
+
+# CPU usage threshold for warnings (percentage)
+# CPU_WARNING_THRESHOLD=80
+
+# Disk usage threshold for warnings (percentage)
+# DISK_WARNING_THRESHOLD=90
+
+# [AWS-SECRET-REMOVED]====================================
+# INTEGRATION SETTINGS
+# [AWS-SECRET-REMOVED]====================================
+
+# Webhook integration (if using thrillwiki-webhook service)
+# WEBHOOK_INTEGRATION=true
+
+# Slack webhook URL for notifications (optional)
+# SLACK_WEBHOOK_URL=https://hooks.slack.com/services/your/webhook/url
+
+# Discord webhook URL for notifications (optional)
+# DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/your/webhook/url
+
+# [AWS-SECRET-REMOVED]====================================
+# USAGE EXAMPLES
+# [AWS-SECRET-REMOVED]====================================
+
+# Example 1: Basic setup with GitHub PAT
+# GITHUB_TOKEN=ghp_your_token_here
+# PULL_INTERVAL=300
+# AUTO_MIGRATE=true
+
+# Example 2: Enhanced monitoring setup
+# HEALTH_CHECK_INTERVAL=30
+# MONITOR_RESOURCES=true
+# NOTIFICATION_EMAIL=admin@thrillwiki.com
+# SLACK_WEBHOOK_URL=https://hooks.slack.com/services/your/webhook
+
+# Example 3: Development environment with frequent pulls
+# PULL_INTERVAL=60
+# DEBUG_MODE=true
+# VERBOSE_LOGGING=true
+# AUTO_UPDATE_DEPENDENCIES=true
+
+# [AWS-SECRET-REMOVED]====================================
+# INSTALLATION NOTES
+# [AWS-SECRET-REMOVED]====================================
+
+# 1. Copy this file: cp thrillwiki-automation***REMOVED***.example thrillwiki-automation***REMOVED***
+# 2. Set secure permissions: chmod 600 thrillwiki-automation***REMOVED***
+# 3. Customize the settings above for your environment
+# 4. Enable the service: sudo systemctl enable thrillwiki-automation
+# 5. Start the service: sudo systemctl start thrillwiki-automation
+# 6. Check status: sudo systemctl status thrillwiki-automation
+# 7. View logs: sudo journalctl -u thrillwiki-automation -f
+
+# For security, ensure only the ubuntu user can read this file:
+# sudo chown ubuntu:ubuntu thrillwiki-automation***REMOVED***
+# sudo chmod 600 thrillwiki-automation***REMOVED***
\ No newline at end of file
diff --git a/debug-setup-automation.sh b/debug-setup-automation.sh
new file mode 100755
index 00000000..cfa4d0e2
--- /dev/null
+++ b/debug-setup-automation.sh
@@ -0,0 +1,91 @@
+#!/bin/bash
+#
+# Debug version of setup-automation.sh to identify non-interactive mode failures
+#
+
+set -e
+
+# Enable verbose debugging
+set -x
+
+echo "DEBUG: Script started at $(date)"
+echo "DEBUG: Arguments received: $*"
+echo "DEBUG: Total argument count: $#"
+
+# Test the exact command that's failing
+echo "DEBUG: Testing setup-automation.sh with --non-interactive flag"
+echo "DEBUG: NON_INTERACTIVE environment variable before: ${NON_INTERACTIVE:-unset}"
+
+# Simulate the command line parsing logic from setup-automation.sh
+echo "DEBUG: Parsing command line arguments..."
+
+command="${1:-setup}"
+echo "DEBUG: Initial command: $command"
+
+# Parse options (mimicking the main script logic)
+while [[ $# -gt 0 ]]; do
+ echo "DEBUG: Processing argument: $1"
+ case "$1" in
+ --non-interactive)
+ export NON_INTERACTIVE="true"
+ echo "DEBUG: NON_INTERACTIVE flag set to: $NON_INTERACTIVE"
+ shift
+ ;;
+ --force-rebuild)
+ export FORCE_REBUILD="true"
+ echo "DEBUG: FORCE_REBUILD flag set to: $FORCE_REBUILD"
+ shift
+ ;;
+ --debug)
+ export CONFIG_DEBUG="true"
+ echo "DEBUG: CONFIG_DEBUG flag set to: $CONFIG_DEBUG"
+ shift
+ ;;
+ -h|--help)
+ echo "DEBUG: Help requested"
+ exit 0
+ ;;
+ -*)
+ echo "DEBUG: Unknown option: $1"
+ exit 1
+ ;;
+ *)
+ echo "DEBUG: Breaking on non-option argument: $1"
+ break
+ ;;
+ esac
+done
+
+# Update command after option parsing (this might be the bug)
+command="${1:-setup}"
+echo "DEBUG: Final command after parsing: $command"
+echo "DEBUG: Remaining arguments: $*"
+
+echo "DEBUG: NON_INTERACTIVE environment variable after parsing: ${NON_INTERACTIVE:-unset}"
+
+# Test the specific condition that shows the interactive banner
+echo "DEBUG: Testing banner condition..."
+if [[ "$NON_INTERACTIVE" != "true" ]]; then
+ echo "DEBUG: BANNER WOULD BE SHOWN - this is the problem!"
+ echo "DEBUG: NON_INTERACTIVE value: '$NON_INTERACTIVE'"
+ echo "DEBUG: Comparison result: '$NON_INTERACTIVE' != 'true'"
+else
+ echo "DEBUG: Banner would be suppressed (correct behavior)"
+fi
+
+# Test what happens when we call the actual script
+echo "DEBUG: Now calling actual setup-automation.sh with timeout..."
+echo "DEBUG: Command will be: timeout 10s bash scripts/vm/setup-automation.sh setup --non-interactive"
+
+# Add timeout to prevent hanging
+if timeout 10s bash scripts/vm/setup-automation.sh setup --non-interactive 2>&1; then
+ echo "DEBUG: Script completed successfully"
+else
+ exit_code=$?
+ echo "DEBUG: Script failed with exit code: $exit_code"
+ if [[ $exit_code -eq 124 ]]; then
+ echo "DEBUG: Script timed out (likely hanging on interactive prompt)"
+ fi
+fi
+
+echo "DEBUG: Debug script completed at $(date)"
\ No newline at end of file
diff --git a/parks_listing_comprehensive_documentation.md b/parks_listing_comprehensive_documentation.md
new file mode 100644
index 00000000..79cecabf
--- /dev/null
+++ b/parks_listing_comprehensive_documentation.md
@@ -0,0 +1,313 @@
+# Parks Listing Page - Comprehensive Documentation
+
+## Overview
+
+The parks listing page is the primary interface for browsing and discovering theme parks in ThrillWiki. It provides search, filtering, and listing capabilities with both grid and list view modes.
+
+## Current Architecture
+
+### Models
+
+#### Park Model (`parks/models/parks.py`)
+The core Park model contains these key fields:
+- **Basic Info**: `name`, `slug`, `description`, `status`
+- **Operations**: `opening_date`, `closing_date`, `operating_season`
+- **Metadata**: `size_acres`, `website`, `average_rating`
+- **Statistics**: `ride_count`, `coaster_count` (manual fields)
+- **Relationships**:
+ - `operator` (ForeignKey to Company)
+ - `property_owner` (ForeignKey to Company)
+ - `photos` (GenericRelation)
+ - `location` (OneToOneField via ParkLocation reverse relation)
+
+#### Park Status System
+The status system uses predefined choices with corresponding CSS classes:
+
+**Status Options:**
+- `OPERATING`: "Operating" - Green badge (`bg-green-100 text-green-800`)
+- `CLOSED_TEMP`: "Temporarily Closed" - Yellow badge (`bg-yellow-100 text-yellow-800`)
+- `CLOSED_PERM`: "Permanently Closed" - Red badge (`bg-red-100 text-red-800`)
+- `UNDER_CONSTRUCTION`: "Under Construction" - Blue badge (`bg-blue-100 text-blue-800`)
+- `DEMOLISHED`: "Demolished" - Gray badge (`bg-gray-100 text-gray-800`)
+- `RELOCATED`: "Relocated" - Purple badge (`bg-purple-100 text-purple-800`)
+
+**Status Badge Implementation:**
+```html
+
+ {{ park.get_status_display }}
+
+```
+
+**CSS Classes:**
+```css
+.status-badge {
+ @apply inline-flex items-center px-3 py-1 text-sm font-medium rounded-full;
+}
+
+.status-operating {
+ @apply text-green-800 bg-green-100 dark:bg-green-700 dark:text-green-50;
+}
+
+.status-closed {
+ @apply text-red-800 bg-red-100 dark:bg-red-700 dark:text-red-50;
+}
+
+.status-construction {
+ @apply text-yellow-800 bg-yellow-100 dark:bg-yellow-600 dark:text-yellow-50;
+}
+```
+
+#### ParkLocation Model (`parks/models/location.py`)
+Handles geographic data with PostGIS support:
+- **Coordinates**: `point` (PointField with SRID 4326)
+- **Address**: `street_address`, `city`, `state`, `country`, `postal_code`
+- **Trip Planning**: `highway_exit`, `parking_notes`, `best_arrival_time`, `seasonal_notes`
+- **OSM Integration**: `osm_id`, `osm_type`
+
+### Views
+
+#### ParkListView (`parks/views.py:212-272`)
+Inherits from `HTMXFilterableMixin` and `ListView`:
+- **Template**: `parks/park_list.html` (full page) or `parks/partials/park_list_item.html` (HTMX)
+- **Pagination**: 20 items per page
+- **Filter Class**: `ParkFilter`
+- **Context**: Includes `view_mode`, `is_search`, `search_query`
+- **Error Handling**: Graceful degradation with error messages
+
+**Key Methods:**
+- `get_template_names()`: Returns different templates for HTMX requests
+- `get_view_mode()`: Handles grid/list toggle
+- `get_queryset()`: Uses `get_base_park_queryset()` with filters applied
+- `get_context_data()`: Adds view mode and search context
+
+#### Supporting View Functions
+- `add_park_button()`: Returns add park button partial
+- `park_actions()`: Returns park actions partial
+- `get_park_areas()`: Dynamic area options for select elements
+- `location_search()`: OpenStreetMap Nominatim API integration
+- `reverse_geocode()`: Coordinate to address conversion
+- `search_parks()`: HTMX search endpoint
+
+### Templates
+
+#### Main Template (`parks/templates/parks/park_list.html`)
+Extends `search/layouts/filtered_list.html` with these sections:
+
+**List Actions Block:**
+- Page title ("Parks")
+- View mode toggle (Grid/List) with HTMX
+- Add Park button (authenticated users only)
+
+**Filter Section Block:**
+- Search autocomplete with Alpine.js
+- Filter form with HTMX updates
+- Loading indicators and accessibility features
+
+**Results List Block:**
+- Contains park results container
+- Includes `park_list_item.html` partial
+
+#### Park List Item Partial (`parks/templates/parks/partials/park_list_item.html`)
+Displays individual park cards:
+- **Grid Layout**: 3-column responsive grid (`md:grid-cols-2 lg:grid-cols-3`)
+- **Card Design**: White background, shadow, hover transform
+- **Content**: Park name (linked), status badge, operator link
+- **Empty State**: Helpful message with option to add parks
+- **Error Handling**: Error display with icon
+
+### Filtering System
+
+#### ParkFilter (`parks/filters.py`)
+Comprehensive filter system with validation:
+
+**Core Filters:**
+- `search`: Multi-field search (name, description, location fields)
+- `status`: Operating status dropdown
+- `operator`: Operating company selector
+- `has_operator`: Boolean filter for operator presence
+
+**Numeric Filters:**
+- `min_rides`: Minimum ride count with validation
+- `min_coasters`: Minimum coaster count with validation
+- `min_size`: Minimum size in acres with validation
+
+**Date Filters:**
+- `opening_date`: Date range filter
+
+**Location Filters:**
+- `location_search`: Search by city, state, country, address
+- `near_location`: Proximity search with geocoding
+- `radius_km`: Search radius (used with near_location)
+- `country_filter`: Country-specific filtering
+- `state_filter`: State/region filtering
+
+**Advanced Features:**
+- Custom `qs` property ensures base queryset with annotations
+- Geocoding integration with OpenStreetMap Nominatim
+- Distance calculations with PostGIS
+- Input validation with custom validators
+
+#### Base Queryset (`parks/querysets.py`)
+Optimized query with:
+- **Relationships**: `select_related('operator', 'property_owner', 'location')`
+- **Prefetches**: `photos`, `rides`
+- **Annotations**:
+ - `current_ride_count`: Live count from related rides
+ - `current_coaster_count`: Live count of roller coasters
+- **Ordering**: Alphabetical by name
+
+### Forms
+
+#### ParkForm (`parks/forms.py:54-312`)
+Comprehensive form for park creation/editing:
+- **Model Fields**: All Park model fields
+- **Location Fields**: Separate fields for coordinates and address
+- **Widgets**: Tailwind CSS styled with dark mode support
+- **Validation**: Coordinate range validation and precision handling
+- **Location Integration**: Automatic ParkLocation creation/update
+
+#### ParkAutocomplete (`parks/forms.py:11-38`)
+Search autocomplete functionality:
+- **Search Attributes**: Park name matching
+- **Related Data**: Includes operator and owner information
+- **Formatting**: Status and location display in results
+
+### Styling & Design
+
+#### Theme System
+Based on Tailwind CSS v4 with custom design tokens:
+- **Primary Color**: `#4f46e5` (Vibrant indigo)
+- **Secondary Color**: `#e11d48` (Vibrant rose)
+- **Accent Color**: `#8b5cf6`
+- **Font**: Poppins sans-serif
+- **Dark Mode**: Class-based toggle support
+
+#### Card Design Pattern
+Consistent across the application:
+```css
+.card {
+ @apply p-6 bg-white border rounded-lg shadow-lg dark:bg-gray-800 border-gray-200/50 dark:border-gray-700/50;
+}
+
+.card-hover {
+ @apply transition-transform transform hover:-translate-y-1;
+}
+```
+
+#### Grid System
+Adaptive grid with responsive breakpoints:
+```css
+.grid-cards {
+ @apply grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3;
+}
+
+.grid-adaptive {
+ @apply grid gap-6;
+ grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+}
+```
+
+#### Status Badges
+Semantic color coding with dark mode support:
+- Consistent padding: `px-3 py-1`
+- Typography: `text-sm font-medium`
+- Shape: `rounded-full`
+- Colors: Contextual based on status type
+
+### JavaScript Integration
+
+#### HTMX Features
+- **Dynamic Loading**: Park list updates without page refresh
+- **Search**: Real-time search with debouncing (300ms delay)
+- **Filters**: Form submission with URL state management
+- **View Modes**: Toggle between grid/list with state preservation
+- **Pagination**: Seamless page navigation
+- **Error Handling**: Custom error displays with HX-Trigger events
+
+#### Alpine.js Components
+- **Search Interface**: Query state management and escape key handling
+- **Filter Integration**: Form state synchronization
+- **Accessibility**: ARIA attributes for screen readers
+
+### API Integration
+
+#### OpenStreetMap Nominatim
+- **Search Endpoint**: Location autocomplete with 10 result limit
+- **Geocoding**: Address to coordinate conversion
+- **Reverse Geocoding**: Coordinate to address lookup
+- **Error Handling**: Graceful fallbacks for API failures
+- **Rate Limiting**: 5-second timeout for requests
+
+#### Location Utilities
+- **Coordinate Normalization**: Precision handling for lat/lng
+- **English Name Extraction**: Multi-language support
+- **Address Parsing**: Comprehensive address component handling
+
+### Performance Optimizations
+
+#### Database Queries
+- **Select Related**: Minimize N+1 queries for relationships
+- **Prefetch Related**: Efficient loading of many-to-many relations
+- **Annotations**: Database-level calculations for counts
+- **Distinct**: Prevent duplicate results from joins
+
+#### Frontend Performance
+- **HTMX**: Partial page updates reduce bandwidth
+- **Debouncing**: Search input optimization
+- **Lazy Loading**: Progressive content loading
+- **Caching**: Template fragment caching where appropriate
+
+### Accessibility Features
+
+#### Screen Reader Support
+- **Semantic HTML**: Proper heading hierarchy and landmarks
+- **ARIA Labels**: Descriptive labels for interactive elements
+- **Focus Management**: Keyboard navigation support
+- **Loading States**: Screen reader announcements for dynamic content
+
+#### Keyboard Navigation
+- **Escape Key**: Closes search suggestions
+- **Tab Order**: Logical focus sequence
+- **Enter/Space**: Activates buttons and links
+
+### Error Handling
+
+#### Graceful Degradation
+- **Query Failures**: Empty queryset with error message
+- **Filter Errors**: Form validation with user feedback
+- **API Timeouts**: Fallback to basic functionality
+- **JavaScript Disabled**: Basic form submission still works
+
+#### User Feedback
+- **Loading Indicators**: Spinner animations during requests
+- **Error Messages**: Clear, actionable error descriptions
+- **Empty States**: Helpful guidance when no results found
+- **Success States**: Confirmation of actions taken
+
+## Current Strengths
+
+1. **Comprehensive Filtering**: Rich set of filter options for various use cases
+2. **Performance**: Optimized queries with proper relationships and annotations
+3. **User Experience**: Smooth HTMX interactions with instant feedback
+4. **Responsive Design**: Works well on all device sizes
+5. **Accessibility**: Good screen reader and keyboard support
+6. **Status System**: Clear, well-designed status indicators
+7. **Location Integration**: PostGIS-powered geographic capabilities
+8. **Search Experience**: Real-time search with autocomplete
+9. **Error Handling**: Graceful degradation and user feedback
+10. **Dark Mode**: Consistent theming across light/dark modes
+
+## Areas for Enhancement
+
+1. **Location Filtering**: Hierarchical location filtering (Country → State → City)
+2. **Advanced Search**: More sophisticated search capabilities
+3. **Map Integration**: Geographic visualization of results
+4. **Bulk Operations**: Multi-select actions for parks
+5. **Export Functionality**: CSV/JSON export of filtered results
+6. **Bookmarking**: Save filter combinations
+7. **Recent Searches**: Search history functionality
+8. **Advanced Sorting**: Multiple sort criteria
+9. **Preview Mode**: Quick preview without navigation
+10. **Comparison Tools**: Side-by-side park comparisons
+
+This documentation provides a comprehensive foundation for understanding the current parks listing implementation and serves as a baseline for planning improvements while preserving the existing strengths and design patterns.
diff --git a/parks_listing_improvement_plan.md b/parks_listing_improvement_plan.md
new file mode 100644
index 00000000..648301e7
--- /dev/null
+++ b/parks_listing_improvement_plan.md
@@ -0,0 +1,700 @@
+# Parks Listing Page - Comprehensive Improvement Plan
+
+## Executive Summary
+
+This document outlines a comprehensive improvement plan for the ThrillWiki parks listing page, focusing on enhanced location-based filtering with a hierarchical Country → State → City approach, while preserving the current design theme, park status implementation, and user experience patterns.
+
+## Primary Focus: Hierarchical Location Filtering
+
+### 1. Enhanced Location Model Structure
+
+#### 1.1 Country-First Approach
+**Objective**: Implement a cascading location filter starting with countries, then drilling down to states/regions, and finally cities.
+
+**Current State**:
+- Flat location fields in `ParkLocation` model
+- Basic country/state/city filters without hierarchy
+- No standardized country/region data
+
+**Proposed Enhancement**:
+```python
+# New model structure to support hierarchical filtering
+class Country(models.Model):
+ name = models.CharField(max_length=100, unique=True)
+ code = models.CharField(max_length=3, unique=True) # ISO 3166-1 alpha-3
+ region = models.CharField(max_length=100) # e.g., "Europe", "North America"
+ park_count = models.IntegerField(default=0) # Denormalized for performance
+
+ class Meta:
+ verbose_name_plural = "Countries"
+ ordering = ['name']
+
+class State(models.Model):
+ name = models.CharField(max_length=100)
+ country = models.ForeignKey(Country, on_delete=models.CASCADE, related_name='states')
+ code = models.CharField(max_length=10, blank=True) # State/province code
+ park_count = models.IntegerField(default=0)
+
+ class Meta:
+ unique_together = [['name', 'country']]
+ ordering = ['name']
+
+class City(models.Model):
+ name = models.CharField(max_length=100)
+ state = models.ForeignKey(State, on_delete=models.CASCADE, related_name='cities')
+ park_count = models.IntegerField(default=0)
+
+ class Meta:
+ verbose_name_plural = "Cities"
+ unique_together = [['name', 'state']]
+ ordering = ['name']
+
+# Enhanced ParkLocation model
+class ParkLocation(models.Model):
+ park = models.OneToOneField('parks.Park', on_delete=models.CASCADE, related_name='location')
+
+ # Hierarchical location references
+ country = models.ForeignKey(Country, on_delete=models.PROTECT)
+ state = models.ForeignKey(State, on_delete=models.PROTECT, null=True, blank=True)
+ city = models.ForeignKey(City, on_delete=models.PROTECT, null=True, blank=True)
+
+ # Legacy fields maintained for compatibility
+ country_legacy = models.CharField(max_length=100, blank=True)
+ state_legacy = models.CharField(max_length=100, blank=True)
+ city_legacy = models.CharField(max_length=100, blank=True)
+
+ # Existing fields preserved
+ point = models.PointField(srid=4326, null=True, blank=True)
+ street_address = models.CharField(max_length=255, blank=True)
+ postal_code = models.CharField(max_length=20, blank=True)
+
+ # Trip planning fields (preserved)
+ highway_exit = models.CharField(max_length=100, blank=True)
+ parking_notes = models.TextField(blank=True)
+ best_arrival_time = models.TimeField(null=True, blank=True)
+ seasonal_notes = models.TextField(blank=True)
+
+ # OSM integration (preserved)
+ osm_id = models.BigIntegerField(null=True, blank=True)
+ osm_type = models.CharField(max_length=10, blank=True)
+```
+
+#### 1.2 Data Migration Strategy
+**Migration Phase 1**: Add new fields alongside existing ones
+**Migration Phase 2**: Populate new hierarchical data from existing location data
+**Migration Phase 3**: Update forms and views to use new structure
+**Migration Phase 4**: Deprecate legacy fields (keep for backwards compatibility)
+
+### 2. Advanced Filtering Interface
+
+#### 2.1 Hierarchical Filter Components
+
+**Location Filter Widget**:
+```html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+#### 2.2 Enhanced Filter Classes
+```python
+class AdvancedParkFilter(ParkFilter):
+ # Hierarchical location filters
+ location_country = ModelChoiceFilter(
+ field_name='location__country',
+ queryset=Country.objects.annotate(
+ park_count=Count('states__cities__parklocation')
+ ).filter(park_count__gt=0),
+ empty_label='All Countries',
+ label='Country'
+ )
+
+ location_state = ModelChoiceFilter(
+ method='filter_location_state',
+ queryset=State.objects.none(), # Will be populated dynamically
+ empty_label='All States/Regions',
+ label='State/Region'
+ )
+
+ location_city = ModelChoiceFilter(
+ method='filter_location_city',
+ queryset=City.objects.none(), # Will be populated dynamically
+ empty_label='All Cities',
+ label='City'
+ )
+
+ # Geographic region filters
+ geographic_region = ChoiceFilter(
+ method='filter_geographic_region',
+ choices=[
+ ('north_america', 'North America'),
+ ('europe', 'Europe'),
+ ('asia_pacific', 'Asia Pacific'),
+ ('latin_america', 'Latin America'),
+ ('middle_east_africa', 'Middle East & Africa'),
+ ],
+ empty_label='All Regions',
+ label='Geographic Region'
+ )
+
+ def filter_location_state(self, queryset, name, value):
+ if value:
+ return queryset.filter(location__state=value)
+ return queryset
+
+ def filter_location_city(self, queryset, name, value):
+ if value:
+ return queryset.filter(location__city=value)
+ return queryset
+
+ def filter_geographic_region(self, queryset, name, value):
+ region_mapping = {
+ 'north_america': ['USA', 'Canada', 'Mexico'],
+ 'europe': ['United Kingdom', 'Germany', 'France', 'Spain', 'Italy'],
+ # ... more mappings
+ }
+ if value in region_mapping:
+ countries = region_mapping[value]
+ return queryset.filter(location__country__name__in=countries)
+ return queryset
+```
+
+### 3. Enhanced User Experience Features
+
+#### 3.1 Smart Location Suggestions
+```javascript
+// Enhanced location autocomplete with regional intelligence
+class LocationSuggestionsSystem {
+ constructor() {
+ this.userLocation = null;
+ this.searchHistory = [];
+ this.preferredRegions = [];
+ }
+
+ // Prioritize suggestions based on user context
+ prioritizeSuggestions(suggestions) {
+ return suggestions.sort((a, b) => {
+ // Prioritize user's country/region
+ if (this.isInPreferredRegion(a) && !this.isInPreferredRegion(b)) return -1;
+ if (!this.isInPreferredRegion(a) && this.isInPreferredRegion(b)) return 1;
+
+ // Then by park count
+ return b.park_count - a.park_count;
+ });
+ }
+
+ // Add breadcrumb navigation
+ buildLocationBreadcrumb(country, state, city) {
+ const breadcrumb = [];
+ if (country) breadcrumb.push({type: 'country', name: country.name, id: country.id});
+ if (state) breadcrumb.push({type: 'state', name: state.name, id: state.id});
+ if (city) breadcrumb.push({type: 'city', name: city.name, id: city.id});
+ return breadcrumb;
+ }
+}
+```
+
+#### 3.2 Location Statistics Display
+```html
+
+
+
Browse by Location
+
+
+ {% for country in top_countries %}
+
+
+
+ {% endfor %}
+
+
+
+
+
+
+
+
+
+
+ {% if park.distance %}
+ {{ park.distance|floatformat:1 }}km away
+ {% endif %}
+ {% if park.search_score %}
+ {{ park.search_score|floatformat:0 }}% match
+ {% endif %}
+
+
+
+
+
+
+
+
+
+