mirror of
https://github.com/pacnpal/thrilltrack-explorer.git
synced 2025-12-20 04:31: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