# ThrillWiki - Theme Park & Ride Encyclopedia

## Overview
ThrillWiki is a community-driven web application for discovering, reviewing, and tracking theme parks, rides, and related entities globally. Its core purpose is to provide a centralized platform for enthusiasts to research attractions and contribute to a collaborative knowledge base through user contributions and reviews, offering a comprehensive encyclopedia for the theme park world.

## Recent Changes (October 8, 2025)

### Critical Bug Fixes - Session 4
- **Fixed CORS Security Vulnerability (P0):** Implemented environment-aware CORS configuration in `upload-image` Edge Function. Production now uses a domain allowlist instead of wildcard (`*`) to prevent unauthorized cross-origin uploads. Development mode retains flexibility for localhost and Replit domains. Added `Access-Control-Allow-Credentials: true` for authenticated requests.
- **Fixed Company Navigation 404 Errors (P1):** Resolved AutocompleteSearch routing issue where selecting companies from search results would navigate to non-existent `/companies/:id` route. Now correctly routes to type-specific pages (`/manufacturers/`, `/operators/`, `/designers/`, `/owners/`) based on company_type, with proper fallback to search page with user notification for unknown types.
- **Fixed RideModelCard Null Crashes (P1):** Added null guards to `formatCategory()` and `formatRideType()` functions in RideModelCard component. Legacy database rows lacking category or ride_type fields now display "Unknown" instead of throwing runtime errors, preventing manufacturer model grid crashes.

### Critical Bug Fixes & Performance Optimization - Session 3
- **Fixed Image Upload Race Condition:** Resolved critical issue in `uploadPendingImages` where parallel uploads using Promise.all could leave orphaned images in Cloudflare on partial failures. Switched to Promise.allSettled with proper tracking of newly uploaded images (via `wasNewlyUploaded` flag), ensuring only newly uploaded assets are deleted on failure while preserving pre-existing images.
- **Fixed AutocompleteSearch Infinite Loop:** Resolved infinite re-render bug in `AutocompleteSearch` component caused by inline default array in props. Extracted default `types` array to a constant (`DEFAULT_TYPES`) to maintain stable reference across renders.
- **Enhanced Test Data Generator:** Implemented missing advanced options (`includeConflicts`, `includeVersionChains`, `escalated`, `expiredLock`) in `seed-test-data` Edge Function. Now properly generates test scenarios including conflicting submissions, version history chains, escalated reports, and expired moderation locks.
- **Fixed PostgreSQL JSON Queries:** Corrected `clearTestData` and `getTestDataStats` functions to use proper PostgreSQL JSON path operators (`->` and `->>`) instead of invalid `contains()` syntax for querying nested `metadata.is_test_data` fields.
- **Added Image ID Validation:** Enhanced `upload-image` Edge Function with format validation for imageId parameter to prevent injection attacks. Now enforces safe character set (alphanumeric, hyphens, underscores) without disrupting UUID formats.
- **Optimized Upload Performance:** Parallelized image uploads for significant performance gains while maintaining atomic failure handling - all uploads succeed or all rollback cleanly.

### Critical Bug Fixes - Session 2
- **Fixed Infinite Loop in Search Hook:** Resolved critical infinite re-render issue in `useSearch` hook by implementing JSON.stringify-based option keying. This creates stable references for search parameters (types, limit, minQuery) even when callers pass inline array literals, preventing infinite fetch loops while maintaining reactivity to option changes.
- **Fixed React Hook Order Violations:** Corrected hook call order in `useSearch` by ensuring all useState declarations come before useMemo/useCallback/useEffect. This prevents HMR (Hot Module Reload) errors and React queue violations during development.
- **Fixed Race Condition in Version History:** Implemented `fetchInProgressRef` guard in `useEntityVersions` hook to prevent concurrent fetch operations that could cause stale data or duplicate requests when rapidly switching between entities.
- **Enhanced Username Validation Stability:** Updated `useUsernameValidation` hook to properly use `useCallback` with stable dependencies, preventing unnecessary re-validation and API calls.
- **Improved Type Safety in Ride Components:** Removed unsafe `as any` type assertions in `ManufacturerModels.tsx` and `RideModelCard.tsx`, replacing them with properly typed interfaces for safer data handling and better IDE support.
- **Enhanced Image Upload Error Recovery:** Improved `imageUploadHelper.ts` to track uploaded image IDs and attempt cleanup deletion from Cloudflare when partial uploads fail, preventing orphaned images in storage.
- **Strengthened Edge Function Reliability:** Added memory leak protection with 10,000-entry limit to rate limiter in `detect-location` Edge Function, and improved topological sort error handling in `process-selective-approval` function.

### Performance & Reliability Improvements - Session 1
- **Added Rate Limiting to Location Detection:** Implemented in-memory rate limiter for `detect-location` Edge Function to prevent abuse. Limits requests to 10 per minute per IP address with automatic cleanup to prevent memory leaks. Returns 429 status with Retry-After header when limit is exceeded.
- **Standardized Error Response Format:** Updated `upload-image` Edge Function to use consistent error response structure across all error paths. All responses now include both `error` (short identifier) and `message` (human-readable description) fields, with optional `details` for additional context. This improves client-side error handling and debugging.
- **Verified HMR Stability:** Investigated and confirmed that Hot Module Reload warnings for `ManufacturerRides.tsx` and `ManufacturerModels.tsx` were transient and have resolved themselves.
- **Validated Cloudflare Integration:** Confirmed `requireSignedURLs` parameter in `upload-image` function is correctly implemented according to Cloudflare Images API specifications.

### Bug Fixes & Code Quality - Session 1
- **Fixed Novu API Integration:** Updated `update-novu-preferences` Edge Function to correctly use Novu's updatePreference API, which requires separate calls for each channel type (email, sms, in_app, push). Implemented proper error handling that tracks per-channel results and returns 502 status with detailed failure information when any channel fails to update.
- **Enhanced Input Validation:** Added validation for userId and channelPreferences in `update-novu-preferences` to prevent undefined access errors and return clear 400 error responses for invalid requests.
- **Fixed TypeScript Errors in Edge Functions:** Corrected null checking for user object in `seed-test-data` function and improved error type handling for JSON parsing operations.
- **Verified Memory Management:** Confirmed that all React hooks (useAuth, useModerationQueue, useEntityVersions) properly clean up intervals and timers in useEffect return statements to prevent memory leaks.

### Security Enhancements
- **Enabled JWT Verification for Image Upload:** Changed `upload-image` Edge Function to `verify_jwt = true` in `supabase/config.toml`. This ensures Supabase validates JWT tokens before the function executes, preventing unauthorized access to image upload/delete operations.
- **Replaced Manual JWT Decoding with Supabase Verification:** Updated `cancel-email-change` Edge Function to use Supabase's built-in `auth.getUser(token)` method with service role client instead of manual base64 decoding. This approach properly verifies JWT tokens using only runtime-available environment variables (SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY) while maintaining admin privileges for database operations.
- **Made Geolocation API Configurable:** Updated `detect-location` Edge Function to use environment variables for geolocation service configuration. The API URL (`GEOLOCATION_API_URL`) and fields (`GEOLOCATION_API_FIELDS`) are now configurable, with sensible defaults (ip-api.com) for easier service switching and testing.

## Recent Changes (October 7, 2025)

### Security Enhancements
- **Fixed Critical Authorization Vulnerability:** Updated `process-selective-approval` Edge Function to properly verify JWT tokens using Supabase's auth verification instead of manual decoding. Now correctly enforces moderator/admin role requirements before allowing content approvals.
- **Enhanced Image Upload Security:** Added banned user checks to `upload-image` Edge Function for both upload (POST) and delete (DELETE) operations to prevent suspended users from managing images.

### Code Quality Improvements
- **React Router v7 Compatibility:** Added future flags (`v7_startTransition`, `v7_relativeSplatPath`) to BrowserRouter to prepare for React Router v7 and eliminate deprecation warnings.

### Architecture Changes
- **Moderation API Update:** Simplified moderation approval API by removing client-supplied `userId` parameter. The authenticated user's ID is now extracted from the verified JWT token on the backend for improved security.

## User Preferences
Preferred communication style: Simple, everyday language.

## System Architecture

### Frontend
- **Tech Stack:** React + TypeScript with Vite, Radix UI + Tailwind CSS (shadcn/ui), TanStack Query for state management, React Router v6 for routing.
- **Component Structure:** Utilizes layout, page-level, reusable UI, and custom domain components.
- **Design System:** HSL-based color system, dark/light theme support, custom gradients, Inter font, responsive and mobile-first design.
- **State Management:** TanStack Query for server state, React Context for authentication, custom hooks for business logic, and Realtime subscriptions for live updates.

### Backend
- **Database (Supabase PostgreSQL):** Stores core entities (parks, rides, companies), location data, review/rating systems, user profiles, content submission workflows, and image metadata.
- **Authentication & Authorization:** Supabase Auth for user management (magic link, email/password), Cloudflare Turnstile for bot protection, role-based access control (user, moderator, admin, superuser), and Row-Level Security (RLS).
- **Content Moderation:** Two-tier submission workflow with dependency tracking, conflict resolution, real-time updates for moderation queues, automated slug generation, and status tracking.
- **Data Access:** Security definer functions for privileged operations, complex joins, aggregated data, full-text search, and real-time subscriptions.

### Image Management
- **Cloudflare Images Integration:** Used for media storage and transformation, with uploads proxied via Supabase Edge Functions. Supports multiple variants for responsive display and stores metadata in Supabase.
- **Upload Workflow:** Uppy dashboard for multi-file uploads, image editor integration, progress tracking, and automatic resizing/optimization via Cloudflare.

### Notification System (Novu)
- **Architecture:** Multi-channel delivery (in-app, email, push), workflow-based templates, per-workflow user preferences, frequency controls, and headless notifications.
- **Features:** Supports subscriber management and preference syncing via Supabase Edge Functions.

### Search & Discovery
- **Multi-Entity Search:** Unified search across parks, rides, and companies with autocomplete, recent history, category/type filtering, and advanced filters.
- **Location Features:** Automatic unit conversion, geo-based preferences, and distance/measurement system settings.

### User Management
- **Profile System:** Customizable usernames, display names, avatars, bios, privacy controls, home park selection, and activity tracking.
- **User Blocking:** Functionality to block users and hide their content.
- **Role Management:** Hierarchical permission system for superuser, admin, moderator, and user roles, with role-specific UI and routes.

### Admin & Moderation
- **Moderation Queue:** Real-time monitoring of submissions, item-level approval/rejection, dependency conflict resolution, bulk actions, and status tracking.
- **Admin Settings:** System-wide configuration with category-based organization and audit trails.
- **Reports System:** Manages user-generated content reports with status workflows.

## External Dependencies

### Third-Party Services
- **Supabase:** PostgreSQL database, authentication, real-time, Edge Functions, storage.
- **Cloudflare:** Cloudflare Images for media storage/transformation, Turnstile for CAPTCHA.
- **Novu:** Multi-channel notification delivery, workflow management.
- **Uppy:** File upload interface and image editor.
- **Google Fonts:** For the Inter typeface.
- **Radix UI:** For accessible UI components.

### API Integrations
- **Supabase Edge Functions:**
    - `upload-image`: Cloudflare Images upload proxy.
    - `trigger-novu-notification`: Sends Novu notifications.
    - `sync-novu-subscriber`: Manages Novu subscribers.
    - `sync-novu-preferences`: Syncs notification preferences.
- **Database Functions (PostgreSQL):** For privacy checks, role-based permissions, and automated tasks.

### Environment Configuration
- Requires `VITE_NOVU_APPLICATION_IDENTIFIER`, `VITE_NOVU_SOCKET_URL`, `VITE_NOVU_API_URL`, `VITE_CLOUDFLARE_ACCOUNT_HASH`, `VITE_SUPABASE_URL`, `VITE_SUPABASE_ANON_KEY`, `VITE_TURNSTILE_SITE_KEY`, and Cloudflare Images API credentials.
- Utilizes feature flags for theme persistence, unit preferences, auto-detection for location settings, and notification channel preferences.