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+**
   ```bash
   python --version  # Should be 3.11 or higher
   ```

2. **UV Package Manager**
   ```bash
   # Install UV if not already installed
   curl -LsSf https://astral.sh/uv/install.sh | sh
   # or
   pip install uv
   ```

3. **PostgreSQL with PostGIS**
   ```bash
   # 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)
   ```bash
   # macOS (Homebrew)
   brew install gdal geos
   
   # Ubuntu/Debian
   sudo apt-get install gdal-bin libgdal-dev libgeos-dev
   ```

5. **Node.js** (for Tailwind CSS)
   ```bash
   # Install Node.js 18+ for Tailwind CSS compilation
   node --version  # Should be 18 or higher
   ```

## 🚀 Quick Start

### 1. Clone and Setup Project

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

# Install Python dependencies using UV
uv sync
```

### 2. Database Setup

```bash
# Create PostgreSQL database and user
createdb thrillwiki
createuser wiki

# Connect to PostgreSQL and setup
psql postgres
```

In the PostgreSQL shell:
```sql
-- 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`](thrillwiki/settings.py)):
```python
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`](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

```bash
# 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`](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:

```bash
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**:

```bash
# 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**:

```bash
# 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`](static/css/src/input.css)
- Compiled: [`static/css/`](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`](TAILWIND_V4_MIGRATION.md)
- **⚡ Quick Reference Guide**: [`TAILWIND_V4_QUICK_REFERENCE.md`](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):
```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

```bash
# 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/`](tests/e2e/)
- Test fixtures: [`tests/fixtures/`](tests/fixtures/)

## 📚 Documentation

### Memory Bank System
The project uses a comprehensive documentation system in [`memory-bank/`](memory-bank/):

- [`memory-bank/activeContext.md`](memory-bank/activeContext.md) - Current development context
- [`memory-bank/documentation/design-system.md`](memory-bank/documentation/design-system.md) - Design system documentation
- [`memory-bank/features/`](memory-bank/features/) - Feature-specific documentation
- [`memory-bank/testing/`](memory-bank/testing/) - Testing documentation and results

### Key Documentation Files
- [Design System](memory-bank/documentation/design-system.md) - UI/UX guidelines and patterns
- [Authentication System](memory-bank/features/auth/) - OAuth and user management
- [Layout Optimization](memory-bank/projects/) - Responsive design implementations

## 🚨 Important Development Rules

### Critical Commands
1. **Server Startup**: Always use the full command sequence:
   ```bash
   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:
   ```bash
   uv add <package>  # ✅ Correct
   pip install <package>  # ❌ Wrong
   ```

3. **Django Commands**: Always prefix with `uv run`:
   ```bash
   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`](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**
   ```bash
   # Connect to database and enable PostGIS
   psql thrillwiki
   CREATE EXTENSION postgis;
   ```

2. **GDAL/GEOS Library Not Found**
   ```bash
   # 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**
   ```bash
   # Kill existing processes
   lsof -ti :8000 | xargs kill -9
   ```

4. **Tailwind CSS Not Compiling**
   ```bash
   # 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/`](memory-bank/) documentation for detailed feature information
2. Review [`memory-bank/testing/`](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/`](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/`](memory-bank/) directory.