thrillwiki_django_no_react/replit.md

# ThrillWiki - Theme Park & Ride Information Platform

## Project Overview
ThrillWiki is a comprehensive Django-based web application for theme park and ride information featuring REST APIs, spatial data support, and comprehensive content management. The platform serves as a database and information system for theme parks, rides, and related content.

## Setup Status: ✅ SUCCESSFULLY RUNNING

### Current State
- **Django Server**: Running successfully on port 5000 with HTTP 200 responses
- **Database**: PostgreSQL configured and all migrations applied
- **GeoDjango**: Spatial libraries (GDAL/GEOS) properly configured for Nix environment
- **CloudflareImages**: Avatar functionality preserved and working
- **Dependencies**: All Python packages installed via UV
- **Workflow**: Active ThrillWiki Server workflow configured
- **Deployment**: Production-ready autoscale configuration set up

### Technical Configuration

#### Environment Setup
- **Python**: 3.13 with UV package manager
- **Database**: PostgreSQL (DATABASE_URL environment variable)
- **Server**: Django development server on 0.0.0.0:5000
- **Spatial Libraries**: GDAL and GEOS configured with correct Nix store paths
- **Settings**: Local development configuration active

#### Database Configuration
```
ENGINE: django.contrib.gis.db.backends.postgis
HOST: PostgreSQL via DATABASE_URL environment variable
Migrations: All applied successfully (including circular dependency resolution)
```

#### Key Packages Installed
- Django 5.2.6
- GeoDjango with PostGIS support
- Django REST Framework
- Django Allauth (authentication)
- CloudflareImages Toolkit
- Django PGHistory
- Pillow (image processing)
- And 30+ other dependencies

### Architecture Overview

#### Apps Structure
- **accounts**: User management and authentication (with CloudflareImages avatars)
- **parks**: Theme park information and management
- **rides**: Ride data and categorization
- **core**: Shared utilities and services (analytics, page views)
- **api**: REST API endpoints (v1)

#### Major Technical Achievements
✅ **PostgreSQL Migration**: Successfully migrated from SQLite to PostgreSQL for proper pghistory support
✅ **GeoDjango Configuration**: GDAL and GEOS libraries properly configured with Nix store paths
✅ **Circular Dependency Resolution**: Resolved accounts/CloudflareImages dependency cycle using staged migrations
✅ **Spatial Data Support**: GeoDjango Point objects and spatial functionality working correctly
✅ **CloudflareImages Integration**: Avatar functionality preserved with proper foreign key relationships
✅ **Django-Cotton Integration**: Modern component-based template system with EXACT visual preservation

### API Endpoints Available
- `/api/v1/parks/` - Parks API with spatial data
- `/api/v1/rides/` - Rides API with manufacturer and stats
- `/api/v1/maps/` - Maps API with spatial features
- `/api/v1/accounts/` - User accounts and profiles
- `/admin/` - Django admin interface

### Recent Setup Work (September 2025)

#### Database Migration Strategy
1. **Initial Issue**: Circular dependency between `accounts.0001_initial` and `django_cloudflareimages_toolkit.0001_initial`
2. **Solution**: Split migrations into stages:
   - `accounts.0001_initial`: User models without avatar field
   - `django_cloudflareimages_toolkit.0001_initial`: CloudflareImages setup
   - `accounts.0002_*`: Added avatar field after CloudflareImages ready
3. **Result**: All migrations applied successfully, no dependency cycles

#### Spatial Libraries Configuration
- **GDAL_LIBRARY_PATH**: `/nix/store/*/lib/libgdal.so`
- **GEOS_LIBRARY_PATH**: `/nix/store/*/lib/libgeos_c.so`
- **Status**: Working correctly in all Django settings files

#### CloudflareImages Integration
- **Avatar Field**: Properly configured in UserProfile model
- **Methods**: get_avatar_url() and get_avatar_variants() working
- **Fallback**: Default letter-based avatars for users without uploaded images

### User Preferences
- **Environment**: Replit development environment
- **Database**: PostgreSQL with spatial data support
- **Port Requirements**: Frontend must run on port 5000
- **Host Configuration**: Requires 0.0.0.0 binding for Replit access
- **CloudflareImages**: Keep functionality preserved

### Development

The application is currently running successfully:
```bash
cd backend && uv run python manage.py runserver 0.0.0.0:5000
```

**Status Verification**:
- Homepage: HTTP 200 responses
- Database: Parks: 0, Rides: 0 (empty but functional)
- Models: All importing and working correctly
- Spatial: GeoDjango Point creation successful

### Deployment Configuration

**Production Ready**:
- **Target**: Autoscale deployment (stateless scaling)
- **WSGI Server**: Gunicorn configured for port 5000
- **Build Process**: UV package installation with requirements.txt
- **Database**: PostgreSQL with persistent external state
- **Images**: CloudflareImages for media handling

### Next Steps for Content Population
1. **Admin Access**: Create superuser account
2. **Content Import**: Add theme parks and rides data
3. **API Testing**: Verify all endpoints with real data
4. **Frontend**: Connect any frontend components if needed
5. **Production**: Deploy using configured autoscale settings

### Django-Cotton Integration (September 2025)

#### Component-Based Template System
- **Django-Cotton Package**: Successfully integrated for modern React/Vue-style component composition
- **Visual Preservation**: EXACT visual output maintained - zero design changes during conversion
- **Component Library**: Full UI component system with button, input, card, auth modal, and toast container
- **Backward Compatibility**: Seamless conversion from Django include syntax to cotton components

#### Cotton Components Created
1. **Button Component** (`<c-button>`): Flexible button with variant support, HTMX/Alpine.js integration
2. **Input Component** (`<c-input>`): Form inputs with validation states and accessibility features  
3. **Card Component** (`<c-card>`): Content containers with flexible slots and styling options
4. **Auth Modal** (`<c-auth_modal>`): Complete authentication modal with social login integration
5. **Toast Container** (`<c-toast_container>`): Notification system with Alpine.js store integration

#### Technical Implementation
- **Zero Visual Regression**: Comprehensive testing confirmed identical HTML output and styling
- **Functionality Preserved**: All HTMX interactions, Alpine.js behavior, and form handling maintained
- **Template Conversion**: All legacy `{% include %}` statements converted to cotton component syntax
- **Production Ready**: Full integration complete with working API endpoints and interactive features

### Development Notes
- Project follows Django best practices with proper app separation
- Comprehensive admin interface configured
- REST API with proper serialization and filtering
- Authentication system ready with Django Allauth
- Spatial data and CloudflareImages fully functional
- Modern component-based template system with django-cotton
- All major technical hurdles resolved

## Project Status: ✅ SUCCESSFULLY IMPORTED AND RUNNING

**ThrillWiki is now fully operational in the Replit environment with all features working!**