thrillwiki_django_no_react/docs/frontend-llm-prompt.md

Frontend Integration Prompt: ThrillWiki Park Filter Endpoints

Project Context

You are working on the NextJS frontend for ThrillWiki, a theme park and ride database application. The Django backend has been updated to support comprehensive park filtering with 24 parameters. Your task is to integrate these filter endpoints into the frontend application.

API Endpoint Information

Base URL Structure

• Main parks endpoint: /parks/
• Individual park: /parks/{park_slug}/
• Filter options: /parks/filter-options/

Critical API Rules

• ALL API endpoints MUST include trailing forward slashes unless ending with query parameters
• Use GET requests for all filtering operations
• Parameters are passed as query strings
• Pagination is handled via page and page_size parameters

Complete Filter Parameters (24 Total)

Pagination & Search

• page (number): Page number for pagination
• page_size (number): Number of results per page
• search (string): Text search across park names and descriptions
• ordering (string): Sort field (name, opening_year, rating, ride_count, etc.)

Geographic Filters

• continent (string): Filter by continent (North America, Europe, Asia, etc.)
• country (string): Filter by country name
• state (string): Filter by state/province
• city (string): Filter by city name

Park Classification

• park_type (string): Park category - options include:
  • THEME_PARK, AMUSEMENT_PARK, WATER_PARK, SAFARI_PARK, ZOO, AQUARIUM, FAMILY_ENTERTAINMENT_CENTER, CARNIVAL, FAIR, OTHER
• status (string): Operational status of the park

Company Relationships

• operator_id (number): Filter by operating company ID
• operator_slug (string): Filter by operating company slug
• property_owner_id (number): Filter by property owner company ID
• property_owner_slug (string): Filter by property owner company slug

Rating Filters

• min_rating (number): Minimum park rating
• max_rating (number): Maximum park rating

Ride Count Filters

• min_ride_count (number): Minimum total number of rides
• max_ride_count (number): Maximum total number of rides
• has_roller_coasters (boolean): Whether park has roller coasters
• min_roller_coaster_count (number): Minimum number of roller coasters
• max_roller_coaster_count (number): Maximum number of roller coasters

Temporal Filters

• opening_year (number): Exact opening year
• min_opening_year (number): Earliest opening year
• max_opening_year (number): Latest opening year

Filter Options Endpoint

The /parks/filter-options/ endpoint provides dynamic filter options based on actual database content:

Response Structure

• continents: Array of available continent strings
• countries: Array of available country strings
• states: Array of available state strings
• cities: Array of available city strings
• park_types: Array of objects with value and label properties
• operators: Array of company objects with operator role
• property_owners: Array of company objects with property owner role
• opening_years: Array of available opening years
• rating_ranges: Object with min/max rating values
• ride_count_ranges: Object with min/max ride count values

TypeScript Integration Requirements

Type Safety

• Create comprehensive TypeScript interfaces for all filter parameters
• Define response types for park list and individual park data
• Use proper union types for optional parameters
• Import types from centralized types file using @/types/api pattern

API Client Structure

• Implement centralized API client with consistent error handling
• Use proper HTTP methods and headers
• Handle pagination metadata in responses
• Implement request/response interceptors for authentication

Frontend Implementation Considerations

User Experience

• Implement progressive disclosure for advanced filters
• Provide clear visual feedback for active filters
• Support filter combinations and complex queries
• Include filter reset and clear functionality

Performance Optimization

• Implement debounced search input
• Cache filter options to reduce API calls
• Use proper loading states during filter operations
• Consider implementing infinite scroll for large result sets

State Management

• Maintain filter state in URL query parameters for bookmarkability
• Sync filter state with component state
• Handle browser back/forward navigation properly
• Persist user filter preferences where appropriate

Data Relationships

Geographic Hierarchy

• Continent → Country → State → City relationship
• Implement cascading dropdowns where appropriate
• Handle cases where geographic data may be incomplete

Company Relationships

• Companies can have multiple roles (operator, property owner)
• Same company may operate multiple parks
• Support filtering by company name or slug

Park-Ride Relationships

• Parks contain multiple rides
• Ride counts include all ride types
• Roller coaster counts are subset of total ride counts

Error Handling Requirements

API Error Responses

• Handle 400 Bad Request for invalid filter parameters
• Handle 404 Not Found for invalid park slugs
• Handle 500 Server Error with appropriate fallbacks
• Implement retry logic for transient failures

User Feedback

• Display clear error messages for failed requests
• Provide fallback content when filters return no results
• Handle network connectivity issues gracefully

Integration Testing Considerations

Filter Validation

• Test all 24 filter parameters individually
• Test filter combinations and edge cases
• Verify proper URL encoding of special characters
• Test pagination with various filter combinations

Data Consistency

• Verify filter options match actual filterable data
• Test geographic filter cascading behavior
• Validate numeric range filters with boundary values

Documentation Requirements

• Update API documentation with all 24 parameters
• Document TypeScript interfaces and their usage
• Provide examples of common filter combinations
• Document error handling patterns and fallback strategies

Backend Compatibility Notes

• All 24 filter parameters are fully supported by Django backend
• Database fields exist for continent and park_type filtering
• API responses include proper pagination metadata
• Filter options endpoint returns real database values, not static lists
• Geographic filtering uses case-insensitive matching
• Company filtering supports both ID and slug-based queries