mirror of
https://github.com/pacnpal/thrilltrack-explorer.git
synced 2025-12-20 09:51:13 -05:00
Add detailed project documentation for ThrillWiki
Adds a new `replit.md` file containing comprehensive documentation for the ThrillWiki project, outlining its overview, tech stack, system architecture (frontend, backend, image management), and user preferences. Replit-Commit-Author: Agent Replit-Commit-Session-Id: f44f1d1b-1dd8-407b-8603-db12902e1a15 Replit-Commit-Checkpoint-Type: full_checkpoint
This commit is contained in:
pac7
237
replit.md
Normal file
237
replit.md
Normal file
@@ -0,0 +1,237 @@
|
|||||||
|
# ThrillWiki - Theme Park & Ride Encyclopedia
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
ThrillWiki is a comprehensive web application for discovering, reviewing, and tracking theme parks, rides, and related entities worldwide. Built as a community-driven encyclopedia, it allows users to explore parks, submit reviews, upload photos, and contribute content through a moderated submission system.
|
||||||
|
|
||||||
|
**Core Purpose:** Provide enthusiasts with a centralized platform to research theme parks, roller coasters, and attractions while building a collaborative knowledge base through user contributions and reviews.
|
||||||
|
|
||||||
|
**Tech Stack:**
|
||||||
|
- Frontend: React + TypeScript with Vite
|
||||||
|
- UI Framework: Radix UI + Tailwind CSS (shadcn/ui)
|
||||||
|
- Backend: Supabase (PostgreSQL + Auth + Storage + Realtime)
|
||||||
|
- Image Storage: Cloudflare Images (via Edge Functions)
|
||||||
|
- Notifications: Novu (multi-channel notification system)
|
||||||
|
- File Uploads: Uppy
|
||||||
|
- State Management: TanStack Query (React Query)
|
||||||
|
|
||||||
|
## User Preferences
|
||||||
|
|
||||||
|
Preferred communication style: Simple, everyday language.
|
||||||
|
|
||||||
|
## System Architecture
|
||||||
|
|
||||||
|
### Frontend Architecture
|
||||||
|
|
||||||
|
**Component Structure:**
|
||||||
|
- Layout components (Header, Footer, AdminHeader) provide consistent navigation
|
||||||
|
- Page-level components for major routes (Parks, Rides, Profile, Admin)
|
||||||
|
- Reusable UI components from shadcn/ui library
|
||||||
|
- Custom domain components (parks, rides, manufacturers, reviews, moderation)
|
||||||
|
|
||||||
|
**State Management:**
|
||||||
|
- TanStack Query for server state and caching
|
||||||
|
- React Context for authentication state (AuthProvider)
|
||||||
|
- Custom hooks for business logic (useAuth, useUserRole, useSearch, useUnitPreferences)
|
||||||
|
- Realtime subscriptions for live updates (moderation stats, submissions)
|
||||||
|
|
||||||
|
**Routing:**
|
||||||
|
- React Router v6 with nested routes
|
||||||
|
- Dynamic slug-based routes for entities (parks/:slug, rides/:rideSlug)
|
||||||
|
- Protected admin routes with role-based access control
|
||||||
|
|
||||||
|
**Design System:**
|
||||||
|
- HSL-based color system with CSS variables
|
||||||
|
- Dark/light theme support via ThemeProvider
|
||||||
|
- Custom gradients and effects for "thrill" aesthetic
|
||||||
|
- Inter font family for typography
|
||||||
|
- Responsive design with mobile-first approach
|
||||||
|
|
||||||
|
### Backend Architecture
|
||||||
|
|
||||||
|
**Database Schema (Supabase PostgreSQL):**
|
||||||
|
- Core entities: parks, rides, companies (manufacturers/designers/operators/property_owners)
|
||||||
|
- Location system with hierarchical data (countries, states, cities)
|
||||||
|
- Review and rating system with moderation
|
||||||
|
- User profiles with privacy controls and preferences
|
||||||
|
- Content submission workflow with approval queue
|
||||||
|
- Image metadata tracking (linked to Cloudflare)
|
||||||
|
- Notification preferences and templates
|
||||||
|
|
||||||
|
**Authentication & Authorization:**
|
||||||
|
- Supabase Auth for user management
|
||||||
|
- Magic link and email/password authentication
|
||||||
|
- Cloudflare Turnstile CAPTCHA for bot protection
|
||||||
|
- Role-based access control (user, moderator, admin, superuser)
|
||||||
|
- Row-level security (RLS) policies for data access
|
||||||
|
- Profile field-level privacy controls
|
||||||
|
|
||||||
|
**Content Moderation System:**
|
||||||
|
- Two-tier submission workflow (submission → submission_items)
|
||||||
|
- Dependency tracking for related entities (rides depend on parks)
|
||||||
|
- Conflict resolution for duplicate/missing entities
|
||||||
|
- Realtime updates for moderation queues
|
||||||
|
- Automated slug generation with uniqueness checks
|
||||||
|
- Status tracking (pending, approved, rejected)
|
||||||
|
|
||||||
|
**Data Access Patterns:**
|
||||||
|
- Security definer functions for privileged operations
|
||||||
|
- Complex joins for entity relationships (parks with rides, operators, locations)
|
||||||
|
- Aggregated data (ratings, review counts, ride counts)
|
||||||
|
- Full-text search capabilities
|
||||||
|
- Realtime subscriptions for live data updates
|
||||||
|
|
||||||
|
### Image Management
|
||||||
|
|
||||||
|
**Cloudflare Images Integration:**
|
||||||
|
- Upload via Supabase Edge Function proxy
|
||||||
|
- Two-step upload process (get URL → upload file)
|
||||||
|
- Multiple image variants for responsive display
|
||||||
|
- Assignment system for entity images (banner, card, gallery)
|
||||||
|
- Local preview support before upload
|
||||||
|
- Image metadata stored in Supabase
|
||||||
|
|
||||||
|
**Upload Workflow:**
|
||||||
|
- Uppy dashboard for multi-file uploads
|
||||||
|
- Image editor integration for cropping/adjustments
|
||||||
|
- Progress tracking and status updates
|
||||||
|
- Entity-specific galleries (parks, rides, companies)
|
||||||
|
- Automatic resizing and optimization via Cloudflare
|
||||||
|
|
||||||
|
### Notification System (Novu)
|
||||||
|
|
||||||
|
**Architecture:**
|
||||||
|
- Multi-channel delivery (in-app, email, push, SMS planned)
|
||||||
|
- Workflow-based templates (review replies, new followers, system announcements)
|
||||||
|
- Per-workflow user preferences
|
||||||
|
- Frequency controls and digest settings
|
||||||
|
- Subscriber management via Supabase Edge Functions
|
||||||
|
- Headless notifications with custom UI
|
||||||
|
|
||||||
|
**Migration Strategy:**
|
||||||
|
- Backward compatibility with legacy notification preferences
|
||||||
|
- Automatic migration from old email/push settings
|
||||||
|
- Granular channel and workflow controls
|
||||||
|
- Delivery tracking and analytics
|
||||||
|
|
||||||
|
### Search & Discovery
|
||||||
|
|
||||||
|
**Multi-Entity Search:**
|
||||||
|
- Unified search across parks, rides, and companies
|
||||||
|
- Autocomplete with debounced queries
|
||||||
|
- Recent search history (localStorage)
|
||||||
|
- Category and type filtering
|
||||||
|
- Advanced filters (technical specs, stats, location)
|
||||||
|
|
||||||
|
**Location Features:**
|
||||||
|
- Automatic unit conversion (metric/imperial)
|
||||||
|
- Geo-based preferences with auto-detection
|
||||||
|
- Distance and measurement system preferences
|
||||||
|
- Temperature unit preferences
|
||||||
|
|
||||||
|
### User Management
|
||||||
|
|
||||||
|
**Profile System:**
|
||||||
|
- Customizable usernames with validation
|
||||||
|
- Display names and avatars (Cloudflare Images)
|
||||||
|
- Bio and personal information
|
||||||
|
- Privacy controls for fields (date of birth, location, pronouns)
|
||||||
|
- Home park selection
|
||||||
|
- Activity tracking (reviews, submissions)
|
||||||
|
|
||||||
|
**User Blocking:**
|
||||||
|
- Block/unblock functionality
|
||||||
|
- Hidden content from blocked users
|
||||||
|
- Privacy-respecting implementation
|
||||||
|
|
||||||
|
**Role Management:**
|
||||||
|
- Hierarchical permission system
|
||||||
|
- Superuser can manage all roles
|
||||||
|
- Admin can manage moderators
|
||||||
|
- Moderator can manage content
|
||||||
|
- Role-specific UI elements and routes
|
||||||
|
|
||||||
|
### Admin & Moderation
|
||||||
|
|
||||||
|
**Moderation Queue:**
|
||||||
|
- Realtime submission monitoring
|
||||||
|
- Item-level approval/rejection
|
||||||
|
- Dependency conflict resolution
|
||||||
|
- Bulk actions support
|
||||||
|
- Status tracking and filtering
|
||||||
|
|
||||||
|
**Admin Settings:**
|
||||||
|
- System-wide configuration (Novu integration, etc.)
|
||||||
|
- Category-based settings organization
|
||||||
|
- Audit trail for changes
|
||||||
|
- Superuser-only access
|
||||||
|
|
||||||
|
**Reports System:**
|
||||||
|
- User-generated content reports
|
||||||
|
- Status workflow (pending, reviewed, resolved)
|
||||||
|
- Moderator actions tracking
|
||||||
|
|
||||||
|
## External Dependencies
|
||||||
|
|
||||||
|
### Third-Party Services
|
||||||
|
|
||||||
|
**Supabase:**
|
||||||
|
- PostgreSQL database with RLS
|
||||||
|
- Authentication and user management
|
||||||
|
- Real-time subscriptions
|
||||||
|
- Edge Functions for serverless logic
|
||||||
|
- Storage for metadata (images stored on Cloudflare)
|
||||||
|
|
||||||
|
**Cloudflare:**
|
||||||
|
- Cloudflare Images for media storage and transformation
|
||||||
|
- Direct upload API integration
|
||||||
|
- Automatic image optimization
|
||||||
|
- Multiple variant support for responsive images
|
||||||
|
|
||||||
|
**Novu:**
|
||||||
|
- Multi-channel notification delivery
|
||||||
|
- Workflow management and templates
|
||||||
|
- Subscriber preferences
|
||||||
|
- Headless notification center
|
||||||
|
- Email, push, and in-app notifications
|
||||||
|
|
||||||
|
**Uppy:**
|
||||||
|
- File upload interface
|
||||||
|
- Image editor integration
|
||||||
|
- Progress tracking
|
||||||
|
- Dashboard UI component
|
||||||
|
- XHR upload transport
|
||||||
|
|
||||||
|
**Additional Services:**
|
||||||
|
- Cloudflare Turnstile for CAPTCHA
|
||||||
|
- Google Fonts (Inter)
|
||||||
|
- Radix UI for accessible components
|
||||||
|
|
||||||
|
### API Integrations
|
||||||
|
|
||||||
|
**Supabase Edge Functions:**
|
||||||
|
- `upload-image`: Proxy for Cloudflare Images upload
|
||||||
|
- `trigger-novu-notification`: Send notifications via Novu
|
||||||
|
- `sync-novu-subscriber`: Manage Novu subscribers
|
||||||
|
- `sync-novu-preferences`: Sync notification preferences
|
||||||
|
|
||||||
|
**Database Functions (PostgreSQL):**
|
||||||
|
- `can_view_profile_field`: Privacy check for profile fields
|
||||||
|
- `get_user_management_permissions`: Role-based permissions
|
||||||
|
- Security definer functions for privileged operations
|
||||||
|
- Trigger functions for automated tasks
|
||||||
|
|
||||||
|
### Environment Configuration
|
||||||
|
|
||||||
|
**Required Variables:**
|
||||||
|
- `VITE_NOVU_APPLICATION_IDENTIFIER`: Novu app ID
|
||||||
|
- `VITE_NOVU_SOCKET_URL`: Novu WebSocket endpoint
|
||||||
|
- `VITE_NOVU_API_URL`: Novu API endpoint
|
||||||
|
- Supabase credentials (injected by hosting platform)
|
||||||
|
- Cloudflare Images API credentials (stored in Supabase secrets)
|
||||||
|
|
||||||
|
**Feature Flags:**
|
||||||
|
- Theme persistence via localStorage
|
||||||
|
- Unit preferences (metric/imperial)
|
||||||
|
- Auto-detection for location-based settings
|
||||||
|
- Notification channel preferences
|
||||||
Reference in New Issue
Block a user