thrillwiki_django_no_react/README.md

ThrillWiki Development Environment Setup

ThrillWiki is a modern Django web application for theme park and roller coaster enthusiasts, featuring a sophisticated dark theme design with purple-to-blue gradients, HTMX interactivity, and comprehensive park/ride information management.

🏗️ Technology Stack

• Backend: Django 5.0+ with GeoDjango (PostGIS)
• Frontend: HTMX + Alpine.js + Tailwind CSS
• Database: PostgreSQL with PostGIS extension
• Package Management: UV (Python package manager)
• Authentication: Django Allauth with Google/Discord OAuth
• Styling: Tailwind CSS with custom dark theme
• History Tracking: django-pghistory for audit trails
• Testing: Pytest + Playwright for E2E testing

📋 Prerequisites

Required Software

1. Python 3.11+

   python --version  # Should be 3.11 or higher
   

2. UV Package Manager

   # Install UV if not already installed
   curl -LsSf https://astral.sh/uv/install.sh | sh
   # or
   pip install uv
   

3. PostgreSQL with PostGIS

   # macOS (Homebrew)
   brew install postgresql postgis
   
   # Ubuntu/Debian
   sudo apt-get install postgresql postgresql-contrib postgis
   
   # Start PostgreSQL service
   brew services start postgresql  # macOS
   sudo systemctl start postgresql  # Linux
   

4. GDAL/GEOS Libraries (for GeoDjango)

   # macOS (Homebrew)
   brew install gdal geos
   
   # Ubuntu/Debian
   sudo apt-get install gdal-bin libgdal-dev libgeos-dev
   

5. Node.js (for Tailwind CSS)

   # Install Node.js 18+ for Tailwind CSS compilation
   node --version  # Should be 18 or higher
   

🚀 Quick Start

1. Clone and Setup Project

# Clone the repository
git clone <repository-url>
cd thrillwiki_django_no_react

# Install Python dependencies using UV
uv sync

2. Database Setup

# Create PostgreSQL database and user
createdb thrillwiki
createuser wiki

# Connect to PostgreSQL and setup
psql postgres

In the PostgreSQL shell:

-- Set password for wiki user
ALTER USER wiki WITH PASSWORD 'thrillwiki';

-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE thrillwiki TO wiki;

-- Enable PostGIS extension
\c thrillwiki
CREATE EXTENSION postgis;
\q

3. Environment Configuration

The project uses these database settings (configured in thrillwiki/settings.py):

DATABASES = {
    "default": {
        "ENGINE": "django.contrib.gis.db.backends.postgis",
        "NAME": "thrillwiki",
        "USER": "wiki", 
        "PASSWORD": "thrillwiki",
        "HOST": "192.168.86.3",  # Update to your PostgreSQL host
        "PORT": "5432",
    }
}

Important: Update the HOST setting in thrillwiki/settings.py to match your PostgreSQL server location:

• Use "localhost" or "127.0.0.1" for local development
• Current setting is "192.168.86.3" - update this to your PostgreSQL server IP
• For local development, change to "localhost" in settings.py

4. Database Migration

# Run database migrations
uv run manage.py migrate

# Create a superuser account
uv run manage.py createsuperuser

Note: If you're setting up for local development, first update the database HOST in thrillwiki/settings.py from "192.168.86.3" to "localhost" before running migrations.

5. Start Development Server

CRITICAL: Always use this exact command sequence for starting the development server:

lsof -ti :8000 | xargs kill -9; find . -type d -name "__pycache__" -exec rm -r {} +; uv run manage.py tailwind runserver

This command:

• Kills any existing processes on port 8000
• Cleans Python cache files
• Starts Tailwind CSS compilation
• Runs the Django development server

The application will be available at: http://localhost:8000

🛠️ Development Workflow

Package Management

ALWAYS use UV for package management:

# Add new Python packages
uv add <package-name>

# Add development dependencies
uv add --dev <package-name>

# Never use pip install - always use UV

Django Management Commands

ALWAYS use UV for Django commands:

# Correct way to run Django commands
uv run manage.py <command>

# Examples:
uv run manage.py makemigrations
uv run manage.py migrate
uv run manage.py shell
uv run manage.py createsuperuser
uv run manage.py collectstatic

# NEVER use these patterns:
# python manage.py <command>        ❌ Wrong
# uv run python manage.py <command> ❌ Wrong

CSS Development

The project uses Tailwind CSS v4 with a custom dark theme. CSS files are located in:

• Source: static/css/src/input.css
• Compiled: static/css/ (auto-generated)

Tailwind automatically compiles when using the tailwind runserver command.

Tailwind CSS v4 Migration

This project has been migrated from Tailwind CSS v3 to v4. For complete migration details:

• 📖 Full Migration Documentation: TAILWIND_V4_MIGRATION.md
• ⚡ Quick Reference Guide: TAILWIND_V4_QUICK_REFERENCE.md

Key v4 Changes:

• New CSS-first approach with @theme blocks
• Updated utility class names (e.g., outline-none → outline-hidden)
• New opacity syntax (e.g., bg-blue-500/50 instead of bg-blue-500 bg-opacity-50)
• Enhanced performance and smaller bundle sizes

Custom Theme Variables (available in CSS):

var(--color-primary)    /* #4f46e5 - Indigo-600 */
var(--color-secondary)  /* #e11d48 - Rose-600 */
var(--color-accent)     /* #8b5cf6 - Violet-500 */
var(--font-family-sans) /* Poppins, sans-serif */

🏗️ Project Structure

thrillwiki_django_no_react/
├── accounts/           # User account management
├── analytics/          # Analytics and tracking
├── companies/          # Theme park companies
├── core/              # Core application logic
├── designers/         # Ride designers
├── history/           # History timeline features
├── location/          # Geographic location handling
├── media/             # Media file management
├── moderation/        # Content moderation
├── parks/             # Theme park management
├── reviews/           # User reviews
├── rides/             # Roller coaster/ride management
├── search/            # Search functionality
├── static/            # Static assets (CSS, JS, images)
├── templates/         # Django templates
├── thrillwiki/        # Main Django project settings
├── memory-bank/       # Development documentation
└── .clinerules        # Project development rules

🔧 Key Features

Authentication System

• Django Allauth integration
• Google OAuth authentication
• Discord OAuth authentication
• Custom user profiles with avatars

Geographic Features

• PostGIS integration for location data
• Interactive park maps
• Location-based search and filtering

Content Management

• Park and ride information management
• Photo galleries with upload capabilities
• User-generated reviews and ratings
• Content moderation system

Modern Frontend

• HTMX for dynamic interactions
• Alpine.js for client-side behavior
• Tailwind CSS with custom dark theme
• Responsive design (mobile-first)

🧪 Testing

Running Tests

# Run Python tests
uv run pytest

# Run with coverage
uv run coverage run -m pytest
uv run coverage report

# Run E2E tests with Playwright
uv run pytest tests/e2e/

Test Structure

• Unit tests: Located within each app's tests/ directory
• E2E tests: tests/e2e/
• Test fixtures: tests/fixtures/

📚 Documentation

Memory Bank System

The project uses a comprehensive documentation system in memory-bank/:

• memory-bank/activeContext.md - Current development context
• memory-bank/documentation/design-system.md - Design system documentation
• memory-bank/features/ - Feature-specific documentation
• memory-bank/testing/ - Testing documentation and results

Key Documentation Files

• Design System - UI/UX guidelines and patterns
• Authentication System - OAuth and user management
• Layout Optimization - Responsive design implementations

🚨 Important Development Rules

Critical Commands

1. Server Startup: Always use the full command sequence:

   lsof -ti :8000 | xargs kill -9; find . -type d -name "__pycache__" -exec rm -r {} +; uv run manage.py tailwind runserver
   

2. Package Management: Only use UV:

   uv add <package>  # ✅ Correct
   pip install <package>  # ❌ Wrong
   

3. Django Commands: Always prefix with uv run:

   uv run manage.py <command>  # ✅ Correct
   python manage.py <command>  # ❌ Wrong
   

Database Configuration

• Ensure PostgreSQL is running before starting development
• PostGIS extension must be enabled
• Update database host settings for your environment

GeoDjango Requirements

• GDAL and GEOS libraries must be properly installed
• Library paths are configured in thrillwiki/settings.py for macOS Homebrew
• Current paths: /opt/homebrew/lib/libgdal.dylib and /opt/homebrew/lib/libgeos_c.dylib
• May need adjustment based on your system's library locations (Linux users will need different paths)

🔍 Troubleshooting

Common Issues

1. PostGIS Extension Error

   # Connect to database and enable PostGIS
   psql thrillwiki
   CREATE EXTENSION postgis;
   

2. GDAL/GEOS Library Not Found

   # macOS (Homebrew): Current paths in settings.py
   GDAL_LIBRARY_PATH = "/opt/homebrew/lib/libgdal.dylib"
   GEOS_LIBRARY_PATH = "/opt/homebrew/lib/libgeos_c.dylib"
   
   # Linux: Update paths in settings.py to something like:
   # GDAL_LIBRARY_PATH = "/usr/lib/x86_64-linux-gnu/libgdal.so"
   # GEOS_LIBRARY_PATH = "/usr/lib/x86_64-linux-gnu/libgeos_c.so"
   
   # Find your library locations
   find /usr -name "libgdal*" 2>/dev/null
   find /usr -name "libgeos*" 2>/dev/null
   find /opt -name "libgdal*" 2>/dev/null
   find /opt -name "libgeos*" 2>/dev/null
   

3. Port 8000 Already in Use

   # Kill existing processes
   lsof -ti :8000 | xargs kill -9
   

4. Tailwind CSS Not Compiling

   # Ensure Node.js is installed and use the full server command
   node --version
   uv run manage.py tailwind runserver
   

Getting Help

1. Check the memory-bank/ documentation for detailed feature information
2. Review memory-bank/testing/ for known issues and solutions
3. Ensure all prerequisites are properly installed
4. Verify database connection and PostGIS extension

🎯 Next Steps

After successful setup:

1. Explore the Admin Interface: http://localhost:8000/admin/
2. Browse the Application: http://localhost:8000/
3. Review Documentation: Check memory-bank/ for detailed feature docs
4. Run Tests: Ensure everything works with uv run pytest
5. Start Development: Follow the development workflow guidelines above

---

Happy Coding! 🎢✨

For detailed feature documentation and development context, see the memory-bank/ directory.