# Django ThrillWiki Source Analysis - Symfony Conversion Foundation

**Date:** January 7, 2025  
**Analyst:** Roo (Architect Mode)  
**Purpose:** Complete analysis of Django ThrillWiki for Symfony conversion planning  
**Status:** Source Analysis Phase - Complete Foundation Documentation

## Executive Summary

This document provides a comprehensive analysis of the current Django ThrillWiki implementation to serve as the definitive source for planning and executing a Symfony conversion. The analysis covers all architectural layers, entity relationships, features, and implementation patterns that must be replicated or adapted in Symfony.

## Project Overview

ThrillWiki is a sophisticated Django-based theme park and ride database application featuring:

- **18 Django Apps** with distinct responsibilities
- **PostgreSQL + PostGIS** for geographic data
- **HTMX + Tailwind CSS** for modern frontend interactions
- **Comprehensive history tracking** via django-pghistory
- **User-generated content** with moderation workflows
- **Social authentication** and role-based access control
- **Advanced search** and autocomplete functionality
- **Media management** with approval workflows

## Source Architecture Analysis

### Core Framework Stack

```
Django 5.0+ (Python 3.11+)
├── Database: PostgreSQL + PostGIS
├── Frontend: HTMX + Tailwind CSS + Alpine.js
├── Authentication: django-allauth (Google, Discord)
├── History: django-pghistory + pgtrigger
├── Media: Pillow + django-cleanup
├── Testing: Playwright + pytest
└── Package Management: UV
```

### Django Apps Architecture

#### **Core Entity Apps (Business Logic)**
1. **parks** - Theme park management with geographic location
2. **rides** - Ride database with detailed specifications
3. **operators** - Companies that operate parks
4. **property_owners** - Companies that own park property
5. **manufacturers** - Companies that manufacture rides
6. **designers** - Companies/individuals that design rides

#### **User Management Apps**
7. **accounts** - Extended User model with profiles and top lists
8. **reviews** - User review system with ratings and photos

#### **Content Management Apps**
9. **media** - Photo management with approval workflow
10. **moderation** - Content moderation and submission system

#### **Supporting Service Apps**
11. **location** - Geographic services with PostGIS
12. **analytics** - Page view tracking and trending content
13. **search** - Global search across all content types
14. **history_tracking** - Change tracking and audit trails
15. **email_service** - Email management and notifications

#### **Infrastructure Apps**
16. **core** - Shared utilities and base classes
17. **avatars** - User avatar management
18. **history** - History visualization and timeline

## Entity Relationship Model

### Primary Entities & Relationships

```mermaid
erDiagram
    Park ||--|| Operator : "operated_by (required)"
    Park ||--o| PropertyOwner : "owned_by (optional)"
    Park ||--o{ ParkArea : "contains"
    Park ||--o{ Ride : "hosts"
    Park ||--o{ Location : "located_at"
    Park ||--o{ Photo : "has_photos"
    Park ||--o{ Review : "has_reviews"
    
    Ride ||--|| Park : "belongs_to (required)"
    Ride ||--o| ParkArea : "located_in"
    Ride ||--o| Manufacturer : "manufactured_by"
    Ride ||--o| Designer : "designed_by"
    Ride ||--o| RideModel : "instance_of"
    Ride ||--o| RollerCoasterStats : "has_stats"
    
    User ||--|| UserProfile : "has_profile"
    User ||--o{ Review : "writes"
    User ||--o{ TopList : "creates"
    User ||--o{ EditSubmission : "submits"
    User ||--o{ PhotoSubmission : "uploads"
    
    RideModel ||--o| Manufacturer : "manufactured_by"
    RideModel ||--o{ Ride : "installed_as"
```

### Key Entity Definitions (Per .clinerules)

- **Parks MUST** have an Operator (required relationship)
- **Parks MAY** have a PropertyOwner (optional, usually same as Operator)
- **Rides MUST** belong to a Park (required relationship)
- **Rides MAY** have Manufacturer/Designer (optional relationships)
- **Operators/PropertyOwners/Manufacturers/Designers** are distinct entity types
- **No direct Company entity references** (replaced by specific entity types)

## Django-Specific Implementation Patterns

### 1. Model Architecture Patterns

#### **TrackedModel Base Class**
```python
@pghistory.track()
class Park(TrackedModel):
    # Automatic history tracking for all changes
    # Slug management with historical preservation
    # Generic relations for photos/reviews/locations
```

#### **Generic Foreign Keys**
```python
# Photos can be attached to any model
photos = GenericRelation(Photo, related_query_name='park')

# Reviews can be for parks, rides, etc.
content_type = models.ForeignKey(ContentType)
object_id = models.PositiveIntegerField()
content_object = GenericForeignKey('content_type', 'object_id')
```

#### **PostGIS Geographic Fields**
```python
# Location model with geographic data
location = models.PointField(geography=True, null=True, blank=True)
coordinates = models.JSONField(default=dict, blank=True)  # Legacy support
```

### 2. Authentication & Authorization

#### **Extended User Model**
```python
class User(AbstractUser):
    ROLE_CHOICES = [
        ('USER', 'User'),
        ('MODERATOR', 'Moderator'), 
        ('ADMIN', 'Admin'),
        ('SUPERUSER', 'Superuser'),
    ]
    role = models.CharField(max_length=20, choices=ROLE_CHOICES, default='USER')
    user_id = models.CharField(max_length=20, unique=True)  # Public ID
```

#### **Social Authentication**
- Google OAuth2 integration
- Discord OAuth2 integration
- Turnstile CAPTCHA protection
- Email verification workflows

### 3. Frontend Architecture

#### **HTMX Integration**
```python
# HTMX-aware views
def search_suggestions(request):
    if request.htmx:
        return render(request, 'search/partials/suggestions.html', context)
    return render(request, 'search/full_page.html', context)
```

#### **Template Organization**
```
templates/
├── base/ - Base layouts and components
├── [app]/ - App-specific templates
│   └── partials/ - HTMX partial templates
├── account/ - Authentication templates
└── pages/ - Static pages
```

### 4. Content Moderation System

#### **Submission Workflow**
```python
class EditSubmission(models.Model):
    STATUS_CHOICES = [
        ('PENDING', 'Pending Review'),
        ('APPROVED', 'Approved'),
        ('REJECTED', 'Rejected'),
        ('ESCALATED', 'Escalated'),
    ]
    # Auto-approval for moderators
    # Duplicate detection
    # Change tracking
```

### 5. Media Management

#### **Photo Model with Approval**
```python
class Photo(models.Model):
    # Generic foreign key for any model association
    # EXIF data extraction
    # Approval workflow
    # Custom storage backend
    # Automatic file organization
```

## Database Schema Analysis

### Key Tables Structure

#### **Core Content Tables**
- `parks_park` - Main park entity
- `parks_parkarea` - Park themed areas
- `rides_ride` - Individual ride installations
- `rides_ridemodel` - Manufacturer ride types
- `rides_rollercoasterstats` - Detailed coaster specs

#### **Entity Relationship Tables**
- `operators_operator` - Park operating companies
- `property_owners_propertyowner` - Property ownership
- `manufacturers_manufacturer` - Ride manufacturers
- `designers_designer` - Ride designers

#### **User & Content Tables**
- `accounts_user` - Extended Django user
- `accounts_userprofile` - User profiles and stats
- `media_photo` - Generic photo storage
- `reviews_review` - User reviews with ratings
- `moderation_editsubmission` - Content submissions

#### **Supporting Tables**
- `location_location` - Geographic data with PostGIS
- `analytics_pageview` - Usage tracking
- `history_tracking_*` - Change audit trails

#### **History Tables (pghistory)**
- `*_*event` - Automatic history tracking for all models
- Complete audit trail of all changes
- Trigger-based implementation

## URL Structure Analysis

### Main URL Patterns
```
/ - Home with trending content
/admin/ - Django admin interface
/parks/{slug}/ - Park detail pages
/rides/{slug}/ - Ride detail pages
/operators/{slug}/ - Operator profiles
/manufacturers/{slug}/ - Manufacturer profiles
/designers/{slug}/ - Designer profiles
/search/ - Global search interface
/ac/ - Autocomplete endpoints (HTMX)
/accounts/ - User authentication
/moderation/ - Content moderation
/history/ - Change history timeline
```

### SEO & Routing Features
- SEO-friendly slugs for all content
- Historical slug support with automatic redirects
- HTMX-compatible partial endpoints
- RESTful resource organization

## Form System Analysis

### Key Form Types
1. **Authentication Forms** - Login/signup with Turnstile CAPTCHA
2. **Content Forms** - Park/ride creation and editing
3. **Upload Forms** - Photo uploads with validation
4. **Review Forms** - User rating and review submission
5. **Moderation Forms** - Edit approval workflows

### Form Features
- HTMX integration for dynamic interactions
- Comprehensive server-side validation
- File upload handling with security
- CSRF protection throughout

## Search & Autocomplete System

### Search Implementation
```python
# Global search across multiple models
def global_search(query):
    parks = Park.objects.filter(name__icontains=query)
    rides = Ride.objects.filter(name__icontains=query)
    operators = Operator.objects.filter(name__icontains=query)
    # Combine and rank results
```

### Autocomplete Features
- HTMX-powered suggestions
- Real-time search as you type
- Multiple entity type support
- Configurable result limits

## Dependencies & Packages

### Core Django Packages
```toml
Django = "^5.0"
psycopg2-binary = ">=2.9.9"  # PostgreSQL adapter
django-allauth = ">=0.60.1"  # Social auth
django-pghistory = ">=3.5.2"  # History tracking
django-htmx = ">=1.17.2"  # HTMX integration
django-cleanup = ">=8.0.0"  # File cleanup
django-filter = ">=23.5"  # Advanced filtering
whitenoise = ">=6.6.0"  # Static file serving
```

### Geographic & Media
```toml
# PostGIS support requires system libraries:
# GDAL_LIBRARY_PATH, GEOS_LIBRARY_PATH
Pillow = ">=10.2.0"  # Image processing
```

### Development & Testing
```toml
playwright = ">=1.41.0"  # E2E testing
pytest-django = ">=4.9.0"  # Unit testing
django-tailwind-cli = ">=2.21.1"  # CSS framework
```

## Key Django Features Utilized

### 1. **Admin Interface**
- Heavily customized admin for all models
- Bulk operations and advanced filtering
- Moderation workflow integration
- History tracking display

### 2. **Middleware Stack**
```python
MIDDLEWARE = [
    'django.middleware.cache.UpdateCacheMiddleware',
    'whitenoise.middleware.WhiteNoiseMiddleware',
    'core.middleware.PgHistoryContextMiddleware',
    'analytics.middleware.PageViewMiddleware',
    'django_htmx.middleware.HtmxMiddleware',
    # ... standard Django middleware
]
```

### 3. **Context Processors**
```python
TEMPLATES = [{
    'OPTIONS': {
        'context_processors': [
            'moderation.context_processors.moderation_access',
            # ... standard processors
        ]
    }
}]
```

### 4. **Custom Management Commands**
- Data import/export utilities
- Maintenance and cleanup scripts
- Analytics processing
- Content moderation helpers

## Static Assets & Frontend

### CSS Architecture
- **Tailwind CSS** utility-first approach
- Custom CSS in `static/css/src/`
- Component-specific styles
- Dark mode support

### JavaScript Strategy
- **Minimal custom JavaScript**
- **HTMX** for dynamic interactions
- **Alpine.js** for UI components
- Progressive enhancement approach

### Media Organization
```
media/
├── avatars/ - User profile pictures
├── park/[slug]/ - Park-specific photos
├── ride/[slug]/ - Ride-specific photos
└── submissions/ - User-uploaded content
```

## Performance & Optimization

### Database Optimization
- Proper indexing on frequently queried fields
- `select_related()` and `prefetch_related()` usage
- Generic foreign key indexing
- PostGIS spatial indexing

### Caching Strategy
- Basic Django cache framework
- Trending content caching
- Static file optimization via WhiteNoise
- HTMX partial caching

### Geographic Performance
- PostGIS Point fields for efficient spatial queries
- Distance calculations and nearby location queries
- Legacy coordinate support during migration

## Security Implementation

### Authentication Security
- Role-based access control (USER, MODERATOR, ADMIN, SUPERUSER)
- Social login with OAuth2
- Turnstile CAPTCHA protection
- Email verification workflows

### Data Security
- Django ORM prevents SQL injection
- CSRF protection on all forms
- File upload validation and security
- User input sanitization

### Authorization Patterns
```python
# Role-based access in views
@user_passes_test(lambda u: u.role in ['MODERATOR', 'ADMIN'])
def moderation_view(request):
    # Moderator-only functionality
```

## Testing Strategy

### Test Structure
```
tests/
├── e2e/ - Playwright browser tests
├── fixtures/ - Test data fixtures
└── [app]/tests/ - Django unit tests
```

### Testing Approach
- **Playwright** for end-to-end browser testing
- **pytest-django** for unit tests
- **Fixture-based** test data management
- **Coverage reporting** for quality assurance

## Conversion Implications

This Django implementation presents several key considerations for Symfony conversion:

### 1. **Entity Framework Mapping**
- Django's ORM patterns → Doctrine ORM
- Generic foreign keys → Polymorphic associations
- PostGIS fields → Geographic types
- History tracking → Event sourcing or audit bundles

### 2. **Authentication System**
- django-allauth → Symfony Security + OAuth bundles
- Role-based access → Voter system
- Social login → KnpUOAuth2ClientBundle

### 3. **Frontend Architecture**
- HTMX integration → Symfony UX + Stimulus
- Template system → Twig templates
- Static assets → Webpack Encore

### 4. **Content Management**
- Django admin → EasyAdmin or Sonata
- Moderation workflow → Custom service layer
- File uploads → VichUploaderBundle

### 5. **Geographic Features**
- PostGIS → Doctrine DBAL geographic types
- Spatial queries → Custom repository methods

## Next Steps for Conversion Planning

1. **Entity Mapping** - Map Django models to Doctrine entities
2. **Bundle Selection** - Choose appropriate Symfony bundles for each feature
3. **Database Migration** - Plan PostgreSQL schema adaptation
4. **Authentication Migration** - Design Symfony Security implementation
5. **Frontend Strategy** - Plan Twig + Stimulus architecture
6. **Testing Migration** - Adapt test suite to PHPUnit

## References

- [`memory-bank/documentation/complete-project-review-2025-01-05.md`](../documentation/complete-project-review-2025-01-05.md) - Complete Django analysis
- [`memory-bank/activeContext.md`](../../activeContext.md) - Current project status
- [`.clinerules`](../../../.clinerules) - Project entity relationship rules

---

**Status:** ✅ **COMPLETED** - Source analysis foundation established  
**Next:** Entity mapping and Symfony bundle selection planning