feat: major API restructure and Vue.js frontend integration

- Centralize API endpoints in dedicated api app with v1 versioning
- Remove individual API modules from parks and rides apps
- Add event tracking system with analytics functionality
- Integrate Vue.js frontend with Tailwind CSS v4 and TypeScript
- Add comprehensive database migrations for event tracking
- Implement user authentication and social provider setup
- Add API schema documentation and serializers
- Configure development environment with shared scripts
- Update project structure for monorepo with frontend/backend separation

backend/apps/api/__init__.py

@@ -0,0 +1,5 @@
+"""
+Consolidated API app for ThrillWiki.
+
+This app provides a unified, versioned API interface for all ThrillWiki resources.
+"""

backend/apps/api/apps.py

@@ -0,0 +1,17 @@
+"""Django app configuration for the consolidated API."""
+
+from django.apps import AppConfig
+
+
+class ApiConfig(AppConfig):
+    """Configuration for the consolidated API app."""
+
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "apps.api"
+
+    def ready(self):
+        """Import schema extensions when app is ready."""
+        try:
+            import apps.api.v1.schema  # noqa: F401
+        except ImportError:
+            pass

backend/apps/api/v1/__init__.py

@@ -0,0 +1,6 @@
+"""
+ThrillWiki API v1.
+
+This module provides the version 1 REST API for ThrillWiki, consolidating
+all endpoints under a unified, well-documented API structure.
+"""

backend/apps/api/v1/schema.py

@@ -0,0 +1,334 @@
+"""
+Schema extensions and customizations for drf-spectacular.
+
+This module provides custom extensions to improve OpenAPI schema generation
+for the ThrillWiki API, including better documentation and examples.
+"""
+
+from drf_spectacular.openapi import AutoSchema
+from drf_spectacular.utils import OpenApiExample
+from drf_spectacular.types import OpenApiTypes
+
+
+# Custom examples for common serializers
+
+PARK_EXAMPLE = {
+    "id": 1,
+    "name": "Cedar Point",
+    "slug": "cedar-point",
+    "description": "The Roller Coaster Capital of the World",
+    "status": "OPERATING",
+    "opening_date": "1870-07-04",
+    "closing_date": None,
+    "location": {
+        "latitude": 41.4793,
+        "longitude": -82.6833,
+        "city": "Sandusky",
+        "state": "Ohio",
+        "country": "United States",
+        "formatted_address": "Sandusky, OH, United States",
+    },
+    "operator": {
+        "id": 1,
+        "name": "Cedar Fair",
+        "slug": "cedar-fair",
+        "roles": ["OPERATOR", "PROPERTY_OWNER"],
+    },
+    "property_owner": {
+        "id": 1,
+        "name": "Cedar Fair",
+        "slug": "cedar-fair",
+        "roles": ["OPERATOR", "PROPERTY_OWNER"],
+    },
+    "area_count": 15,
+    "ride_count": 70,
+    "operating_rides_count": 68,
+    "roller_coaster_count": 17,
+}
+
+RIDE_EXAMPLE = {
+    "id": 1,
+    "name": "Steel Vengeance",
+    "slug": "steel-vengeance",
+    "description": "A hybrid wooden/steel roller coaster",
+    "category": "ROLLER_COASTER",
+    "status": "OPERATING",
+    "opening_date": "2018-05-05",
+    "closing_date": None,
+    "park": {"id": 1, "name": "Cedar Point", "slug": "cedar-point"},
+    "manufacturer": {
+        "id": 1,
+        "name": "Rocky Mountain Construction",
+        "slug": "rmc",
+        "roles": ["MANUFACTURER"],
+    },
+    "designer": {
+        "id": 1,
+        "name": "Rocky Mountain Construction",
+        "slug": "rmc",
+        "roles": ["DESIGNER"],
+    },
+    "height_feet": 205,
+    "length_feet": 5740,
+    "speed_mph": 74,
+    "inversions": 4,
+    "duration_seconds": 150,
+    "capacity_per_hour": 1200,
+    "minimum_height_inches": 48,
+    "maximum_height_inches": None,
+}
+
+COMPANY_EXAMPLE = {
+    "id": 1,
+    "name": "Cedar Fair",
+    "slug": "cedar-fair",
+    "roles": ["OPERATOR", "PROPERTY_OWNER"],
+}
+
+LOCATION_EXAMPLE = {
+    "latitude": 41.4793,
+    "longitude": -82.6833,
+    "city": "Sandusky",
+    "state": "Ohio",
+    "country": "United States",
+    "formatted_address": "Sandusky, OH, United States",
+}
+
+HISTORY_EVENT_EXAMPLE = {
+    "id": "12345678-1234-5678-9012-123456789012",
+    "pgh_created_at": "2024-01-15T14:30:00Z",
+    "pgh_label": "updated",
+    "pgh_model": "parks.park",
+    "pgh_obj_id": 1,
+    "pgh_context": {
+        "user_id": 42,
+        "request_id": "req_abc123",
+        "ip_address": "192.168.1.100",
+    },
+    "changed_fields": ["name", "description"],
+    "field_changes": {
+        "name": {"old_value": "Cedar Point Amusement Park", "new_value": "Cedar Point"},
+        "description": {
+            "old_value": "America's Roller Coast",
+            "new_value": "The Roller Coaster Capital of the World",
+        },
+    },
+}
+
+PARK_HISTORY_EXAMPLE = {
+    "park": PARK_EXAMPLE,
+    "current_state": PARK_EXAMPLE,
+    "summary": {
+        "total_events": 25,
+        "first_recorded": "2023-01-01T00:00:00Z",
+        "last_modified": "2024-01-15T14:30:00Z",
+        "significant_changes": [
+            {
+                "date": "2024-01-15T14:30:00Z",
+                "event_type": "updated",
+                "description": "Name and description updated",
+            },
+            {
+                "date": "2023-06-01T10:00:00Z",
+                "event_type": "updated",
+                "description": "Operating status changed",
+            },
+        ],
+    },
+    "events": [HISTORY_EVENT_EXAMPLE],
+}
+
+UNIFIED_HISTORY_TIMELINE_EXAMPLE = {
+    "summary": {
+        "total_events": 1250,
+        "events_returned": 100,
+        "event_type_breakdown": {"created": 45, "updated": 180, "deleted": 5},
+        "model_type_breakdown": {
+            "parks.park": 75,
+            "rides.ride": 120,
+            "companies.operator": 15,
+            "companies.manufacturer": 25,
+            "accounts.user": 30,
+        },
+        "time_range": {
+            "earliest": "2023-01-01T00:00:00Z",
+            "latest": "2024-01-15T14:30:00Z",
+        },
+    },
+    "events": [
+        {
+            "id": "event_001",
+            "pgh_created_at": "2024-01-15T14:30:00Z",
+            "pgh_label": "updated",
+            "pgh_model": "parks.park",
+            "pgh_obj_id": 1,
+            "entity_name": "Cedar Point",
+            "entity_slug": "cedar-point",
+            "change_significance": "minor",
+            "change_summary": "Park description updated",
+        },
+        {
+            "id": "event_002",
+            "pgh_created_at": "2024-01-15T12:00:00Z",
+            "pgh_label": "created",
+            "pgh_model": "rides.ride",
+            "pgh_obj_id": 100,
+            "entity_name": "New Roller Coaster",
+            "entity_slug": "new-roller-coaster",
+            "change_significance": "major",
+            "change_summary": "New ride added to park",
+        },
+    ],
+}
+
+
+# OpenAPI schema customizations
+
+
+def custom_preprocessing_hook(endpoints):
+    """
+    Custom preprocessing hook to modify endpoints before schema generation.
+
+    This can be used to filter out certain endpoints, modify their metadata,
+    or add custom documentation.
+    """
+    # Filter out any endpoints we don't want in the public API
+    filtered = []
+    for path, path_regex, method, callback in endpoints:
+        # Skip internal or debug endpoints
+        if "/debug/" not in path and "/internal/" not in path:
+            filtered.append((path, path_regex, method, callback))
+
+    return filtered
+
+
+def custom_postprocessing_hook(result, generator, request, public):
+    """
+    Custom postprocessing hook to modify the generated schema.
+
+    This can be used to add custom metadata, modify response schemas,
+    or enhance the overall API documentation.
+    """
+    # Add custom info to the schema
+    if "info" in result:
+        result["info"]["contact"] = {
+            "name": "ThrillWiki API Support",
+            "email": "api@thrillwiki.com",
+            "url": "https://thrillwiki.com/support",
+        }
+
+        result["info"]["license"] = {
+            "name": "MIT",
+            "url": "https://opensource.org/licenses/MIT",
+        }
+
+    # Add custom tags with descriptions
+    if "tags" not in result:
+        result["tags"] = []
+
+    result["tags"].extend(
+        [
+            {
+                "name": "Parks",
+                "description": "Operations related to theme parks, including CRUD operations and statistics",
+            },
+            {
+                "name": "Rides",
+                "description": "Operations related to rides and attractions within theme parks",
+            },
+            {
+                "name": "History",
+                "description": "Historical change tracking for all entities, providing complete audit trails and version history",
+                "externalDocs": {
+                    "description": "Learn more about pghistory",
+                    "url": "https://django-pghistory.readthedocs.io/",
+                },
+            },
+            {
+                "name": "Statistics",
+                "description": "Statistical endpoints providing aggregated data and insights",
+            },
+            {
+                "name": "Reviews",
+                "description": "User reviews and ratings for parks and rides",
+            },
+            {
+                "name": "Authentication",
+                "description": "User authentication and account management endpoints",
+            },
+            {
+                "name": "Health",
+                "description": "System health checks and monitoring endpoints",
+            },
+            {
+                "name": "Recent Changes",
+                "description": "Endpoints for accessing recently changed entities by type and change category",
+            },
+        ]
+    )
+
+    # Add custom servers if not present
+    if "servers" not in result:
+        result["servers"] = [
+            {
+                "url": "https://api.thrillwiki.com/v1",
+                "description": "Production server",
+            },
+            {
+                "url": "https://staging-api.thrillwiki.com/v1",
+                "description": "Staging server",
+            },
+            {
+                "url": "http://localhost:8000/api/v1",
+                "description": "Development server",
+            },
+        ]
+
+    return result
+
+
+# Custom AutoSchema class for enhanced documentation
+class ThrillWikiAutoSchema(AutoSchema):
+    """
+    Custom AutoSchema class that provides enhanced documentation
+    for ThrillWiki API endpoints.
+    """
+
+    def get_operation_id(self):
+        """Generate meaningful operation IDs."""
+        if hasattr(self.view, "basename"):
+            basename = self.view.basename
+        else:
+            basename = getattr(self.view, "__class__", self.view).__name__.lower()
+            if basename.endswith("viewset"):
+                basename = basename[:-7]  # Remove 'viewset' suffix
+
+        action = self.method_mapping.get(self.method.lower(), self.method.lower())
+        return f"{basename}_{action}"
+
+    def get_tags(self):
+        """Generate tags based on the viewset."""
+        if hasattr(self.view, "basename"):
+            return [self.view.basename.title()]
+        return super().get_tags()
+
+    def get_summary(self):
+        """Generate summary from docstring or method name."""
+        summary = super().get_summary()
+        if summary:
+            return summary
+
+        # Generate from method and model
+        action = self.method_mapping.get(self.method.lower(), self.method.lower())
+        model_name = getattr(self.view, "basename", "resource")
+
+        action_map = {
+            "list": f"List {model_name}",
+            "create": f"Create {model_name}",
+            "retrieve": f"Get {model_name} details",
+            "update": f"Update {model_name}",
+            "partial_update": f"Partially update {model_name}",
+            "destroy": f"Delete {model_name}",
+        }
+
+        return action_map.get(action, f"{action.title()} {model_name}")

backend/apps/api/v1/urls.py

@@ -0,0 +1,142 @@
+"""
+URL configuration for ThrillWiki API v1.
+
+This module provides unified API routing following RESTful conventions
+and DRF Router patterns for automatic URL generation.
+"""
+
+from django.urls import path, include
+from rest_framework.routers import DefaultRouter
+from drf_spectacular.views import (
+    SpectacularAPIView,
+    SpectacularSwaggerView,
+    SpectacularRedocView,
+)
+
+from .viewsets import (
+    ParkViewSet,
+    RideViewSet,
+    ParkReadOnlyViewSet,
+    RideReadOnlyViewSet,
+    LoginAPIView,
+    SignupAPIView,
+    LogoutAPIView,
+    CurrentUserAPIView,
+    PasswordResetAPIView,
+    PasswordChangeAPIView,
+    SocialProvidersAPIView,
+    AuthStatusAPIView,
+    HealthCheckAPIView,
+    PerformanceMetricsAPIView,
+    SimpleHealthAPIView,
+    # History viewsets
+    ParkHistoryViewSet,
+    RideHistoryViewSet,
+    UnifiedHistoryViewSet,
+    # New comprehensive viewsets
+    ParkAreaViewSet,
+    ParkLocationViewSet,
+    CompanyViewSet,
+    RideModelViewSet,
+    RollerCoasterStatsViewSet,
+    RideLocationViewSet,
+    RideReviewViewSet,
+    UserProfileViewSet,
+    TopListViewSet,
+    TopListItemViewSet,
+)
+
+# Create the main API router
+router = DefaultRouter()
+
+# Register ViewSets with descriptive prefixes
+
+# Core models
+router.register(r"parks", ParkViewSet, basename="park")
+router.register(r"rides", RideViewSet, basename="ride")
+
+# Park-related models
+router.register(r"park-areas", ParkAreaViewSet, basename="park-area")
+router.register(r"park-locations", ParkLocationViewSet, basename="park-location")
+
+# Company models
+router.register(r"companies", CompanyViewSet, basename="company")
+
+# Ride-related models
+router.register(r"ride-models", RideModelViewSet, basename="ride-model")
+router.register(
+    r"roller-coaster-stats", RollerCoasterStatsViewSet, basename="roller-coaster-stats"
+)
+router.register(r"ride-locations", RideLocationViewSet, basename="ride-location")
+router.register(r"ride-reviews", RideReviewViewSet, basename="ride-review")
+
+# User-related models
+router.register(r"user-profiles", UserProfileViewSet, basename="user-profile")
+router.register(r"top-lists", TopListViewSet, basename="top-list")
+router.register(r"top-list-items", TopListItemViewSet, basename="top-list-item")
+
+# Register read-only endpoints for reference data
+router.register(r"ref/parks", ParkReadOnlyViewSet, basename="park-ref")
+router.register(r"ref/rides", RideReadOnlyViewSet, basename="ride-ref")
+
+app_name = "api_v1"
+
+urlpatterns = [
+    # API Documentation endpoints
+    path("schema/", SpectacularAPIView.as_view(), name="schema"),
+    path(
+        "docs/",
+        SpectacularSwaggerView.as_view(url_name="api_v1:schema"),
+        name="swagger-ui",
+    ),
+    path(
+        "redoc/", SpectacularRedocView.as_view(url_name="api_v1:schema"), name="redoc"
+    ),
+    # Authentication endpoints
+    path("auth/login/", LoginAPIView.as_view(), name="login"),
+    path("auth/signup/", SignupAPIView.as_view(), name="signup"),
+    path("auth/logout/", LogoutAPIView.as_view(), name="logout"),
+    path("auth/user/", CurrentUserAPIView.as_view(), name="current-user"),
+    path("auth/password/reset/", PasswordResetAPIView.as_view(), name="password-reset"),
+    path(
+        "auth/password/change/", PasswordChangeAPIView.as_view(), name="password-change"
+    ),
+    path("auth/providers/", SocialProvidersAPIView.as_view(), name="social-providers"),
+    path("auth/status/", AuthStatusAPIView.as_view(), name="auth-status"),
+    # Health check endpoints
+    path("health/", HealthCheckAPIView.as_view(), name="health-check"),
+    path("health/simple/", SimpleHealthAPIView.as_view(), name="simple-health"),
+    path(
+        "health/performance/",
+        PerformanceMetricsAPIView.as_view(),
+        name="performance-metrics",
+    ),
+    # History endpoints
+    path(
+        "history/timeline/",
+        UnifiedHistoryViewSet.as_view({"get": "list"}),
+        name="unified-history-timeline",
+    ),
+    path(
+        "parks/<str:park_slug>/history/",
+        ParkHistoryViewSet.as_view({"get": "list"}),
+        name="park-history-list",
+    ),
+    path(
+        "parks/<str:park_slug>/history/detail/",
+        ParkHistoryViewSet.as_view({"get": "retrieve"}),
+        name="park-history-detail",
+    ),
+    path(
+        "parks/<str:park_slug>/rides/<str:ride_slug>/history/",
+        RideHistoryViewSet.as_view({"get": "list"}),
+        name="ride-history-list",
+    ),
+    path(
+        "parks/<str:park_slug>/rides/<str:ride_slug>/history/detail/",
+        RideHistoryViewSet.as_view({"get": "retrieve"}),
+        name="ride-history-detail",
+    ),
+    # Include all router-generated URLs
+    path("", include(router.urls)),
+]